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5 days Hands-on Labs 
Public, Private 

This course combines lectures, demonstrations and laboratory exercises to present the primary 
functions of the OS/2 2.0 control program. Daily exercises provide the student with experience in 
implementing the OS/2 2.0 Application Programming Interface. 

Who Should Take This Course: Systems programmers and engineers who will use OS/2 as a base 
for developing hardware and software products. Persons experienced in programming OS/2 version 
1.x should attend the OS/2 2.0 for OS/2 Software Developers course (WTDPS25C) for an update. 

What You Are Taught: The student will be able to apply the appropriate programming tools and 
procedures to build OS/2 applications that implement these key features: 

• OS/2 Design Goals 

• Application Types 

• 80386/486 Protected Mode Operation 

• Memory Management 

• Thread Management 

• Execution Synchronization Using Semaphores 

• Process Management 

• Interprocess Communication Using Memory /Pipes/Queues 

• File Systems 

• Dynamic Link Libraries 

• Session Management 

• Exception Management 

Prerequisites: Familiarity with the PS/2 operating and programming environment and a working 
knowledge of the C programming language. 



©IBM Corp. 



i 



Novonfeu 19, 19*3 



Course Outline 



Day 1 (AM.) 

Introduction to OS/2 [45 minutes] 

• Design Goals of OS/2 

• Memory Organization 

• Privilege Model 

• Application Programming Interface 

• Multitasking Hierarchy 

Pre-course Quiz [10 minutes] 
OS/2 Application Types [30 minutes] 

• OS/2 Mode Windowed Applications 

• OS/2 Mode Full-Screen Applications 

• DOS/Windows Mode Applications 

Protected Mode [90 minutes] 

• General Purpose and Memory Registers 

• Operating Modes 

• Protection Mechanisms 

• Real Mode Addressing 

• Protected Mode Addressing 

• Memory Exceptions 

Day 1 (P.M.) 

Introduction to OS/2 Programming [30 minutes] 

• Register- Based API 

• Call-Based API 

• C Program Template 

• Function Prototypes 

• Return Codes 

Environment Strings and Command Line Arguments [45 minutes] 

• Obtaining Environment and Command Line Pointers 

• Searching the Environment 

• Environment Strings 

• Command Line 

• C Program Entry State 

Program Development [30 minutes] 

• Programming Tools 

• Header and Include Files 

• Development Process 

• LINK386 

• NMAKE 
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Laboratory Exercise 1 [180 minutes] 



• Introduction to the Enhanced Editor 

• Writing an OS/2 Program 

• IBM Presentation Debugger 

• System Exceptions/Faults 

• Displaying Command Line Arguments 

• Experimenting with DETACH and START 

• WorkFrame/2 



Day 2 (A.M.) 



Memory Management [70 minutes] 

• OS/2 2.0 Memory Model 

• Virtual Address Space 

• Memory Objects 

• Memory Allocation API's 

• Memory Suballocation API's 

Introduction to Multitasking [20 minutes] 



• Serial Multitasking 

• Parallel Multitasking 

• Elements of Multitasking 

Sessions 

Processes 

Threads 



Thread Management [90 minutes] 

• Thread Hierarchy 

• Creating Threads 

• Thread States 

• Thread Priority 

• Configuration Parameters 

• C Programming Considerations 



Day 2 (P.M.) 



Laboratory Exercise 2 [180 minutes] 

• Building a Single Thread OS/2 Application 

• Multitasking Using Two Threads 

• Thread Control 

• Thread Management Using C Functions 



Day 3 (A.M.) 

Synchronizing with Semaphores [90 minutes] 

• Uses of Semaphores 

• Classes and Types of Semaphores 

• Application of OS/2 Semaphores 
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• Event Semaphore API's 

• Mutex Semaphore API's 

• MuxWait Semaphore API's 

OS/2 Timer Services 120 minutes] 

• Synchronous Timer API's 

• Asynchronous Timer API's 

Process Management [70 minutes] 

• Process Resources 

• Creating A Process 

• Process Isolation 

• Testing Process Status 

• Controlling Process Termination 



Day 3 (P.M.) 

Shared Memory Objects [40 minutes] 

• Named Shared Objects 

• Unnamed Shared Objects 

• Shared Memory Allocation API's 

Laboratory Exercise 3 [180 minutes] 

• Synchronizing Threads With Event Semaphores 

• Creating and Managing Processes 

• Synchronizing Parent/Child Processes 

• Exit Routines 



Day 4 (A.M.) 

File Input/Output [60 minutes] 

• OS/2 File Systems 

• Naming OS/2 Files 

• O pe n / Creating Fi le s 

• Standard File Attributes 

• Extended File Attributes 

Interprocess Communication Using Queues [45 minutes] 

■ Client/ Server Interprocess Communication 

• Que Management API's 

Dynamic Link Libraries [90 minutes] 

• Static Linking 

• Dynamic Linking 

• Code Sharing 

• Building a DLL 

• Methods of Dynamic Linking 

• DLL Initialization 

iv 
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Day 4 (P.M.) 



Laboratory Exercise 4 [ISO minutes] 

• Load-Time Dynamic Linking 

• Updating a DLL 

• Run-Time Dynamic Linking 

• DLL Initialization 

• Pipes and Queues 



Day 5 [A.M.j 

Exception Management [90 minutes] 

• System Exceptions 

• Types of Exceptions 

• Exception Handlers 

• Exception Management Data Structures 
■ Exception Management API's 

Session Management [45 minutes] 

• Session Management Components 

• Session Hierarchy 

• Session Management API's 

Interprocess Communication Using Pipes [30 minutes] 

• Standard Input/ Output 

• Anonymous Pipes 

• Named Pipes 

Post -Course Quiz [30 minutes] 

Day 5 (P.M.) 

Laboratory Exercise Completion [open] 



©IBM Corp. 



V 



vi 

® IBM C °T- August 20, 1993 



OS/2 for Software Developers Ver. 2.x 



[CN17400C/N1740] 



References: 

ADG - Application Design Guide, S10G-6260 

CP, - Control Programming Reference, S10G-6263 

G.S. - Getting Started, IBM Developer's Toolkit for OS/2 2.0, 10G6199 

P.G.I - Prog.Guide Vol. I, OS/2 Tech. Lib, S10G-6264 

U.G. - C Set/2 User's Guide, S10G-4444 

Kogan - The Design Of OS/2, Kogan & Deitel, Addison -Wesley 
Letwin - Inside OS/2, Gordon Letwin, Micorsoft Press 



1 . Introduction to OS/2 

- 1 Introduction 

-2 Design Goals - Multitasking, Devlndependence Letwin 9 

-3 Design Goals - Custom and Stable Environment Letwin 15 

-4 Design Goals - 32 Bit Environment 

-5 Design Goals - DOS/Windows Support 

-6 OS/2 2.0 Memory Organization 

-7 OS/2 Privilege Model Kogan 37, ADG 2-11 

-8 Application Programming Interface ADG 1-29 

-9 Layers of OS/2 Kogan 86 

- 10 OS/2 Multitasking Hierarchy Kogan 87 

2. OS/2 Applications 

- 1 Introduction 

-2 Types of Applications 

-3 OS/2 Mode Window Applications 

-4 OS/2 Mode Full Screen Applications 

-5 DOS /Window Mode Applications 

-6 Concurrent Execution of Application Classes 

-7 System Limits - 2.0 vs 1.3 

3. Protected Mode 

- 1 Introduction 

-2 General Purpose Registers Kogan 29,43 

-3 Memory Segment Registers Kogan 43 

-4 Operating Modes 

-5 Protection Mechanisms 

-6 Real Mode Memory Addressing 

-7 Protected Mode Memory Addressing 

-8 Selector Format 

-9 Data Segment Descriptors 

-10 16-Bit Protected Mode Memory Addressing 

-11 32 -Bit Protected Mode Memory Addressing 

-12 FAULT. LST 

-13 First Violation - Part 1 

- 14 First Violation - Part 2 

- 1 5 First Violation - Part 3 

-16 SecondViolation 

- 1 7 Third Violation 

-18 Fourth Violation 

4. Intro to OS/2 Programming 

- 1 Introduction 

•oil 
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-2 OS/2 Application Interface 

-3 DOS Register-based API 

-4 OS/2 Call-Based API 

-5 Using the 'C Language for OS/2 

-6 API Function Prototypes 

-7 _System Calling Convention 

-8 Return Codes 

-9 Class Exercise 

5. Environment Strings and Command Lines 

1 Introduction 

-2 Obtaining Environment and Command Line Pointers 

-3 Searching the Environment 

-4 Environment Strings 

-5 Command Line and Arguments 

-6 C Program Entry State 

-7 DosScanEnv Program Example 

6. Software Development Process 

- 1 Introduction 

-2 Programming Tools G.S. Chp. 4 

-3 Header and Include Files 

-4 OS/2 Development Process 

-5 OS/2 Linker 

-6 NMAKE Program Maintenance Utility 

7. Memory Management P.G.I Chp. 6 

- 1 Introduction 

-2 The Flat Memory Model Kogan 163 

-3 Virtual Address Space Kogan 164 

-4 Memory Objects Kogan 165 

-5 Types of Memory Objects Kogan 165,166 

-6 DosAllocMem CP. 2-6 

-7 DosFreeMem C.P. 2-115 

-8 DosQueryMem C.P. 2-222 

-9 DosSetMem C.P. 2-317 

-10 Suballocation of Memory P. G. 16-14 

-11 DosSubSetMem C.P. 2-361 

-12 DosSubAllocMem, DosSubFreeMem C.P. 2-357,359 

-13 DosSubUnsetMem C.P. 2-364 

8. Intro to Multitasking 

- 1 Introduction 

-2 Multiple Tasks Letwin 41 

-3 Parallel Multitasking Letwin 13, 42 

-4 OS/2 Elements of Multitasking (Sessions) 

5 OS/2 Elements of Multitasking (Processes) Letwin 44 

-6 OS/2 Elements of Multitasking (Threads) Letwin 43, 70 

9. Thread Management P.G.I Chp. 7 

-1 Introduction 

-2 Thread Hierarchy 

-3 An Example of Three Threads 

-4 Another Example of Three Threads 

-5 Thread States 

-6 Priority Classes and Levels Kogan 116 

-7 Dynamic Priority Adjustment Kogan 117 

viii 
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Introduction 
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P.G.I 8-1 
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Application of OS/2 Semaphores 
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11. OS/2 Timer Services P.G.I Chp. 1 
- 1 Introduction 

-2 DosSleep CP. 2-341 

-3 DosStarrTimer C.P. 2-351 

-4 DosAsyncTimer C.P, 2-12 

-5 DosStopTimer C.P. 2-353 



12. Processes p,G. 1 Chp. 7 

- 1 Introduction 

-2 Processes Kogan 87 

-3 Process Resources Letwin 44 

-4 Creating a Process 

-5 DosExecPgm C.P. 2-89 

-6 Process Isolation 

-7 Controlling Child Processes 

-8 Process Concurrency 
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-9 Command Subtrees Letwin 57 

-10 Testing for Child Process Termination P.G.I 2-375 

-1 1 DosWaitChild: Process Subtrees Letwin 64,65 

-12 DosWaitChild: Individual Processes 

- 1 3 DosWaitChild : Process Subtrees 

- 1 4 Performing Cleanup When a Process Ends 

-15 Exit List Sequence 

-16 DosExitList P.G.I 2-98 

13. Shared Objects P.G. 1 6-18 thru 20 
- 1 Introduction 

-2 Two Types of Shared Objects 

-3 Using Named Shared Segments 

-4 Using Unnamed Shared Segments 

-5 DosAllocSharedMem CP. 2-9 

-6 DosGetNamedSharedMem CP. 2-135 

-7 DosGiveSharedMcm CP. 2-141 

-8 DosGetSharedMem CP. 2-139 

14. File Input/Output P.G.I Chp. 2 thru 5 
- 1 Introduction 

-2 OS/2 File Systems P.G.I 2-1 

-3 Mulitple OS/2 File Systems P.G.I 2-2 

-4 Recognizing Dos and OS/2 file P.G.I 2-5 

-5 Naming OS/2 Files P.G.I 3-1 

-6 Using Long File Names P.G. 1 3-3 thru 5 

-7 Opening/Creating Files 

-8 DosOpen CP. 2-158 

-9 Sychronous File Input/Output CP. 2-265, 388 

-10 Asynchronous File Input /Output 

- 1 1 Changing the Size File CP. 2-3 1 2 

- 1 2 Inheriting Files 

-13 Locking Regions of a File CP. 2-304 

-14 Updating File Data/Directory P.G.I 4-5, CP. 2-22,277 

-15 Standard File Attributes P.G.I 5-1 

-16 Extended File Attributes P.G.I 5-1 

-17 Naming Extended Attributes P.G.I 5-2 

-18 Extended Attribute Data Types P.G. 1 5-3 

- 1 9 Extended Attribute Data Structures P.G. 1 5-15 

-20 Example of a Single-Value EA 

-21 Example of a Multi-Value, Single-Type EA 

-22 Example of a Multi-Value, Multi-Type EA 

-23 Preserving EAs P.G.I 5-16 

-24 Managing EAs 

15. Queues p.G. 1 Chp. 10 
-1 Introduction 

-2 Queue Overview 

-3 DosCreateQueue CP. 2-51 

-4 DosOpenQueue CP. 2-170 

-5 DosWriteQueue CP. 2-391 

-6 DosPeekQueue CP. 2-177 

-7 DosReadQueue CP. 2-268 

-8 DosQueryQueue,DosPurgeQue,DosCIoseQueue CP. 2-254, 186, 28 

-9 Monitoring Mulitple Queues 

16. Dynamic Link Libraries 

x 

OIBMCorp. August 20, 1993 



- 1 Introduction 

-2 Static Linking 

-3 Disadvantages of Static Linking 

-4 Advantages and Disadvantages of Dynamic Link Libraries 

-5 Dynamic Links vs Processes 

-6 Dynamic Linking 

-7 Load Time 

-8 Code Sharing: Two Instances of Same .EXE 

-9 Code Sharing: Different .EXE's with Common Subsys 

-10 Code Sharing: Different .EXE's, DLL with Static Data 

-11 Code Sharing: Different .EXE's. DLL with Instance Static Data 

- 1 2 Variables in Main and in the DLL 

-13 Building a DLL 

-14 Preparing the .DLL and Import Library 

- 1 5 Preparing the . EXE 

-16 Methods of Dynamic Linking 

-17 Dynamic Linking at Run Time 

-18 DosLoadModule CP. 2-151 

-19 DosQueryProcAddr, DosFreeModule CP. 2-250, 117 

-20 Data Objects in DLL's 

-21 DLL Initialization 

-22 Flow of Control for DLL Initialization 

-23 _DLL_InitTerm U.G. 225-237 

-24 Types of DLL Initialization 

-25 Initializing the C Run -time Environment U.G. 234 

-26 Invoking _CRT_init: App. Statically linked (/Gd-), No User DLLs 

-27 Invoking _CRT_init: App. Dynamically Linked (/Gd), No User DLLs 

-28 Invoking _CRT_init: App. and User DLL Dynamically Linked {/Gd} 

-29 Invoking _CRT_init: App. Dynamically Linked (/Gd), User DLL Static (/Gd-) 
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-2 System Exceptions P.G.I 13-1 

-3 Type of Exceptions P.G.I 13-1 

-4 Signal Exceptions P.G. 1 13-6 
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18. Session Management P.G. 1 7-32 thru 37 
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Design Goals of OS/2 
Application Programming Interface 
Multitasking Hierarchy 
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Design Goals 



Multitasking With Performance/Response Equal to Single Tasking: 

0 Parallel multitasking through preemptive scheduling using 
a single CPU. 

0 At any time, CPU usage may be unpredictably switched to 
another task. 



Device Independence: 
0 The application issues commands to a generic device, 
v The device driver translates the commands to fit the characteristics 



of the actual hardware. 



0 The application does not need to know the specifics of the hardware. 
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OS/2 



Custom and Stable Execution Environment: 

0 Extended physical memory addressing to 4 GB. 

0 Virtual memory addressing to 64 TB. 

0 Memory protection ensures errors in one application do not 
corrupt any other application. 

0 Isolation of applications from one another and from the 
operating system. 
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OS/2 



0 Fully exploit the capabilities of the Intel 80386 / 80486 processors 

0 Provide a 32-bit programming environment that is portable to 
other architectures. 

0 Binary compatibility with the OS/2 1.x 16-bit executables. 
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OS/2 



DOS / Windows Application Support In A Protected Environment: 
0 Up to 240 concurrent sessions. 

0 Over 630 KB of standard memory available to the application. 

0 Up to 32 MB of EMS, 16 MB of XMS and 512 MB of DPMI (DOS 
Protected Mode Interface) memory available to the application. 

0 Foreground or background execution in either a full screen or 
windowed session. 

20MTFOOS HOJOS 
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OS/2 2.x Memory Organization 



Linear Address Space 




Region 



1 MB — I 



DOS/ 
Windows 
Address 

Space 



512MB 



OS/2 
jli. 

Address 
Space 



4 GB 
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OS/2 Privilege Model 




2OMmO07B2O708 



I 



1-7 



Application Programming Interface 
(API) 



0 More than 700 application services define the capability 
of OS/2 and Presentation Manager. 

0 The API call prefix defines the service provided: 

Dev - device support 

Dos - control program (kernel) 

Gpi - graphics programming 

Kbd - keyboard direct access 

Mou - mouse direct access 

Pic - picture support 

Prf - profiles (initialization files) 

Spl - spooler 

Vio - alphanumeric text (video output) 
Win - windows 
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App 



Layers of OS/2 



App or 

Library Routine 



Dynamic Link API 



Session Manager 



I/O Subsystems (KBD,MOU,VIO) 



Kernel 

File System 
Process Management 



Device Drivers 
Hardware 
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OS/2 Multitasking Hierarchy 




MO 



OS/2 Applications 



OS/2 Mode Applications 
DOS Mode Applications 
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Types of Applications 



0 OS/2 Mode Windowed Applications: 

Each applications runs in a separate session 

May share the display with other windowed applications. 

Applications multitask. 

0 OS/2 Mode Full- Screen Applications: 

Applications do not share the display with other applications. 
Applications multitask. 

0 DOS / Window Mode Applications: 
OS/2 emulates PC-DOS. 

MOST applications will run the same as under PC-DOS. 
Applications may execute in a window or full screen. 
Applications multitask. 



9Z0709 



2-2 



OS/2 Mode W/indowed Applications 



0 Presentation Manager Applications: 

Creates one or more windows to present functions to the user. 
May generate full graphics. 

Should adhere to the SAA Common User Access definition. 
Is aware that the system is being shared with other applications. 
Applications multitask. 

0 Text- Windowed Applications: 

Do not explicitly create windows. 

OS/2 provides a default window for execution. 

Applications multitask. 
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OS/2 Mode Full-Screen Applications 



® Do not share the display with other applications. 



@ Each application runs in its own full-screen session. 



0 Applications multitask. 
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DOS / Window Mode Applications 



0 Applications originally developed for PC-DOS that adhere 
to the PC-DOS specification. 

0 Window applications written to the 3.1 sepcifications. 

@ Applications execute in a window or full screen. 



2-5 



Concurrent Execution of Application Classes 
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System Limits - 2.x vs 1.3 

2.0 1.3 





Sys 


TJsr 


Sys 


Usr 


Sessions 










Full-SfTPpn 

Granhic- Window /pM) 




9S^ 


1 ft. 

lO 


1 9 

1Z 




9S9 


J.O 




Text- Window 


255 


2S2 


1 u 


1 ft 






9^9 


i 
1 


i 
1 




A AO ft 


/irift^ 
H-UOD 


<1 i 
Ml 


3U4 


Threads 


4095 


4065 


512 


483 


Threads per Process 


4095 


4065 


54 


54 


Open File Handles - system wide 


64K 




64K 




Global Semaphores - system wide 


64000 


64000 


512 


512 


User signals per process 






3 




Minimum stack for Thread 




8K 




4K 


Timers per Thread 






1 




Process Address Space 




512M 




512M 
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Notes 
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Protected Mode 



Register Set 
Operating Modes 
Accessing Memory 
Exceptions 



3-1 



General Purpose Registers 



General 
Purpose 
Registers 



Special 
Purpose 



Accumulator EAX 
Base EBX 
Count ECX 
Data I/O EDX 
Source Index 
Destination Index 
Base Pointer 
Stack Pointer 



ESf 
EDI 
EBP 
ESP 

Instruction Pointer BP 
EFLAGS 



«S1 16 


15 8:7 0 




AH 


AL 




BH 


BL 




CH 


CL 




DH 


CL 




9 




□ 




BP 




3 d 




P 




FLAGS 



AX 
BX 

cx 

DX 
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| | Available in the 80386/486 
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Memory Segment Registers 



9) The 8088/80286 have 4 Segment Registers 



CODE SEGMENT 
DATA SEGMENT 
EXTRA SEGMENT 
STACK SEGMENT 



0 These Segment Registers point to the beginning 
of the 4 currently addressable memory segments 

0 Additional segments registers, FS and GS, are 
available in the 80386/486. 



MEMORY 
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Operating Modes 




A0-A19 



A20-A31 



{Protected mode only) 



D0-D31 



0 Real Mode: 

1MB physical address space 
Runs like a fast 8086 
Default power-on mode 

0 Protected Mode: 

4 GB physical memory 

Memory Protection 

Hardware Task Switches 

64 Terabyte Per Task Virtual Memory Support 

0 Virtual 8086 Protected Mode 

Supports execution of 8086/8088 programs in a 
protected mode environment. 
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Protection Mechanisms 



0 Protects the user from programming errors: 
Out of range accesses 
Incorrect I/O 

Overlaying interrupt vectors 

0 Protects processes from other processes: 
Processes are isolated 

0 Protects the operating system from the user: 
Multiple privilege levels 
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Real Mode Memory Addressing 



SEGMENT OFFSET 




1 MB 



0 There is a direct relationship between the segment register value 
and the physical memory address. 

0 [SEGMENT * 16] + OFFSET = 20 bit physical address 
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Protected Mode Memory Addressing 



SEGMENT 
SELECTOR 



ADDRESSING 
MECHANISM 



SEGMENT 



+ 

OFFSET 



ELEMENT 



0 The address = Selector : Offset. 

Q) The Selector does not point directly to memory. 

@ Selector : Offset can refer to an element not currently 
present in physical memory (logical address). 



20PMDDC6 920709 



Selector Format 



15 



3 2 10 



INDEX 



71 



RPL 



@ The RPL bits indicate the privilege level of the task. 

0 The TI bit points to the Global (0) or Local (1) Descriptor Table. 

0 The other 13 bits specify an entry in one of the two tables. 



32 14 46 

2 BYTES/SEGMENT x 2 SEGMENTS = 2 BYTES 



20P.vkjqo? 3Zt?709 



3-8 



Data Segment Descriptors 



UMfT 


BASE 0-15 


BASE 16-23 


ACCESS RIGHTS 


„ - « A UMI1 
G B 0 v 

t 16-19 


BASE 24-31 



□ Available in 80386/486. Reserved in the 80286 



0 8 bytes that describe a Data Segment. 

0 Contains a full 32-bit address (24-bit in the 80286). 

0 Contains segment size (limit) and access rights. 
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16-Bit Protected Mode Memory Addressing 



SELECTOR 



13-Bit 
Index 



16-Bit 



OFFSET 



Descriptor 
Table 




Address 



Descriptor Format 



LIMIT 



BASE 0-15 



BASE 1 6-23 | ACCESS RIGHTS 
RESERVED 



16-Bit 



24-Bit 



MEMORY 




ELEMENT 




16MB 
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13-Bit 
Index 



31 



32-Bit Protected Mode Memory Addressing 

SELECTOR OFFSET 



16-Bit 



32-Bit 



Descriptor 
Table 



Base 
Address 



32-Bit Linear Address 



Dir 
10 



Frame 



Pa 



Page 
Direclory 



I— <i Page Table 



23 











A 




Base 31. .24 


G 


B 


0 


V 












L 





Offset 

12 



1 2 Bits 



I'll 



Pay-; (-aire 



32 



Bits 




ELEMENT 
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FAULT.LST 



.386 ; allow 386 instructions 

INCLUDE LIB OS2386 .LIB 

0000 CODE32 SEGMENT DWORD USE32 PUBLIC 'CODE' 

0000 CODE 32 ENDS 

000 0 DATA32 SEGMENT DWORD USE32 PUBLIC ' DATA' 

0000 DATA32 ENDS 

DGROUP GROUP data32 

ASSUME CSiFLAT, DS I FLAT, SStFLAT, £5 t FLAT 

000 0 Stack32 SEGMENT DWORD USE32 STACK 'STACK' 

0000 2000 I db 8192 DUP (?) 

00 

] 

2000 Stac)c32 ENDS 

00 00 data 3 2 SEGMENT 

PUBLIC msgl,uisgllefi,msg2,msg21en 

0000 41 20 6D 65 73 73 msgl db 'A message ', Odh , Oah 

61 67 65 0D OA 

000B = 000B msgllen equ S-msgl 

000B 48 65 6C 6C 6F 20 mag2 db 'Hello OS/2 world l!!',0dh.0ah 

4F 53 2F 32 20 
57 6F 72 6C 64 
20 21 21 21 0D 
OA 

0021 - 0016 msg21en equ $-msg2 

0021 data32 ENDS 
0000 code 3 2 SEGMENT 

0000 77777777 varl dd 77777777h 

0004 Starts 

0004 SB 0D 00000000 R mov ecx, varl [ access OK 

00QA 8A 2D 0000000b R mov ah ,msgl+ntsgllen ; access OK 

0010 8A 0D 00000021 R mov cl ,msg2+msg21en ; access OK. WHY ?7 

0016 8A 0D 00001000 R mov el,msg2+0f £5h ; 1st violation 

001C 89 0D 000O00O0 R mov varl, ecx ; 2nd violation 

0022 BC 00OO0000 mov esp,0 

0027 50 push eax ; 3rd violation 



; 4th violation 
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0028 code32 ENDS 

END Start 
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First Violation - Part 1 



SFAULT.EXE 



[C:]FAULT 



System Error - FAULT.EXE 



S YS31 75 

A program in this session encountered a problem ; 
cannot continue. 



Options 



!* End program/command/operation 
• Display register information 



OK 



HELP 
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First Violation - Part 2 



[C:]FAULT 



FAULT.EXE 



System Error - FAULT.EXE 



SYS3175 



A program generated an access violation at 00010016. 
FAULT.EXE 0001 

P1=00000001 P2=00021000 P3=XXXXXXXX P4=XXXXXXXX 
EAX = 000D000D EBX=00000000 ECX=77774800 EDX=00000000 
ESUOOODOOOO EOI=00000000 
DS=0053 DSACC=dOf3 DSUM=1bfrftff 
ES=0053 ESACC=dOf3 ESLIM=1 bffftff 
FS=150b FSACC=00f3 FSLIM=00000030 
GS=O000 GSACC='*" GSLIM = 
CS:EIP=OOSb:00010016 CSACC=dOdf CSLIM=1 bffffff 
SS:ESP=O053:OOO31fec SSACC=dOf3 S5LIM=1 bfftflf 
EBP=OO0OOOOO FLG =0001 2202 



Options 

> End program/command/operation 
:* Display register information 



OK 
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First Violation - Part 3 



FAULT.EXE 



[C:]FAULT 



System Error - FAULT. EXE 



-SYS3175 ■ 

EXPLANATION: An access violation exception occurred and was 
generated when an attempt was made either to load or store data in 
an inaccessible location t or to execute an inaccessible 
instruction. This exception corresponds to both the Intel 80386 
processor general protection fault (#13), caused by an invalid 
access attempt, and the page fault (#14), caused by an attempt to 
access an uncommitted page or a page with incorrect attributes for 
the desired operation. 

ACTION: If you purchased this program, contact the supplier 
of the program. If you are the developer of this program, 
refer to the information in the register. 



- Options - — 

•End program/command/operation 
■ Display register information 

| OK [ [ HELP | 
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Second Violation 



FAULT.EXE 



,[C:] FAULT 



System Error • FAULT.EXE 



-SYS3175 

A program generated an access violation at 0001001c. 
FAULT, EXE 0001 

P1 =00000002 P2=00010000 P3=XXXXXXXX P4=XXXXXXXX 
EAX=00000000 EBX = 00000000 ECX=77774B48 EDX=00000000 
ESI=00000000 EDI=Q0000000 
DS=D053 DSACC=d0f3 DSLIM=1 bffffff 
ES=00S3 ESACC=d0f3 ESLIM=1 bffffff 
FS=150b FSACC=0Of3 FSL1M=00000030 
GS=0000 GSACC="** GSLIM="*"*** 
CS:EIP=005b:0001001c CSACC=dOdf CSLIM=1 bffffff 
SS'ESP=0053:00031fec SSACC=d0f3 SSLIM=1 bffffff 
EBP=Q0OOOQDO FLG=00012202 



Options 

* End program/command/operation 

• Display register information 



OK 



HELP 
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/ — I 

Third Violation 



FAULT.EXE 



[C:]FAULT 



System Error - FAULT.EXE 



SYS3175 



A program generated an access violation at 00010027. 
FAULT.EXE 0001 

P1 =00000010 P2=ftffffff P3-XXXXXXXX P4-XXXXXXXX 
EAX=00000000 EBX = 000QOOOQ ECX=77777777 EDX=OOO00000 
ESI=OOOO0OO0 EDI=00000000 
DS=00S3 DSACC=d0f3 DSLIM=1bffffff 
ES=0053 ESACC=d0f3 ESLIM=1 bffff'ff 
FS-150b FSACC=00f3 FSL1M = 00000030 

GS=0000 GSACC=**** GSLIM = * 

eS:EIP=005b:00010027 CSACC=dOdf CSLIM=1bffffff 
SS:ESP=0053:0000000O SSACC=d0t3 SSLIMslbffffff 
EBP=00000000 FLG=00012202 



Options ■ 

» End program/command/operation 
■ Display register information 



OK 



HELP 
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Fourth Violation 



FAULT.EXE 



[C:] FAULT 



System Error - FAULT.EXE 



SYS3175 ■ ■ 

A program generated an access violation at 00010028. 
FAULT.EXE 0001 

PI =00000001 P2=ffffffff P3=XXXXXXXX P4=XXXXXXXX 
EAX=00000000 EBX=00000000 ECX=77777777 EDX=00000000 
ESI=00000000 EDI=00000000 
DS=0053 DSACC=d0t3 DSLIM=1 bffffff 
ES=0053 ESACC=d0f3 ESLIM-1 bffffff 
FS=150b FSACC=Q0f3 FSLIM=00000030 

GS=0000 GSACC='*'* GSLIM=* 

CS:EIP=005b:00010028 CSACC=d0df CSL I M=1 bffffff 
SS:E5P=0053:00031fe8 SSACC=d0f3 SSLIM=1 bffffff 
EBP=00O0OO04 FLG=00012202 



Options ■ 

a End program/command/operation 
'M Display register information 



OK | [HELP | 
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Introduction to OS/2 Programming 



API interface 
Return Codes 
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OS/2 Application Interface 



APPLICATION 



APPLICATION 



etc. 





* 

DLL APPLICATION PROGRAM INTERFACE (API ) 






OS/2 KERNEL 



DEVICE DRIVER 



DEVICE DRIVER 



etc. 
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DOS Register-Based API 



APPLICATION 



; terminate program 
MOV AH, 4Ch 
INT 21 H 



PC-DOS 



0 Pass parameters via registers. 

0 Link to DOS through a software interrupt. 

0 Very efficient but, difficult to do from a high-level language. 
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APPLICATION 



PUSH duration 
PUSH frequency 
CALL DosBeep ' 



0 Passing paramters on the stack is compatible with most 
high level languages. 
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Using the C Language for OS/2 



#define INCL BASE h r,r/AV' 0/ ^ Hi 

♦define INCL_NOPMAPI ^Tf>^^ coi^^ i< ~-^'^ 
♦ include <os2.h> - — " ^tT o-? 

int main ( } \J#(L jJofj^tS-^ 

< 



return { NO_ERROR ) ; 



0 OS2.H contains the API function prototypes. 



0 INCL_BASE limits the processing of function prototypes to 
base kernel functions. 
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API Function Prototypes 



VOID APIENTRY DosExit ( ULONG action, /* o=end current thread, l=end process */ 

ULONG result); /* program completion code*/ 



APIRET APIENTRY DosBeep ( ULONG freq, /* frequency of sound in hertz */ 

ULONG dur ) ; /* length of sound in milliseconds */ 



0 ANSI 'C Standard 

(2) Extended 'C compiler error checking 

@ Interface is independent of model of compilation used 



— — " — lt c<,? eta**?"-'-*' J 



4-6 



_System Calling Convention 



APIRET .System DosBeep ( ULONG, ULONG ); 

LOW 

DosBeep ( frequency , duration ) ; 



frequency 



duration 



. — . SP before pushes 



HIGH 



0 Parameters are pushed on the stack in right-to-left order as in normal C. 
0 The 'caller' clears parameters from the stack. 

0 The IBM C/C++ compiler's default method of passing parameters is to 
use a combination hardware registers and the stack . This is called Optlink. 

0 OS/2 ver. lx uses the pascal calling convention . 
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Return Codes 



MASM 



§DosBeep ( 50, 300 ) ; 

OR EAX , EAX 

JHS error 
( JZ> 



API RET rc; 

EC - DosBeep (50, 300); 

if (rc) printf ( "rc=*d Unable to beep speaker\n",ro) ; 



CMP EAX,0 
JNE error 
(JB) 



0 Always returned in the EAX register. 0 = NO_ERROR. 

0 Return codes are documented in the OS/2 2.0 
Technical Library reference materials. 
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Class Exercise 



Given the following 'C function prototype, how many bytes of 
stack space are necessary for the parameters? 



APIKET API ENTRY Dos Write ( 

HFILE hFile, // File handle 

PVOID pBuffer, // Output buffer 

ULONG cbWrite, // Number of bytes to be written 

PULONG pcbActual); // Number of bytes written (returned) 
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Notes 
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Environment Strings and Command Line Arguments 



Accessing the Environment 
Accessing the Command Line 
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Obtaining Environment and Command Line Pointers 



DosGetlnfoB locks ( PTIB *ptib, --> ptr to ThreadlnfoBlockl 

PPIB *ppib ); --> ptr to ProcessInfoBlock 



struct pib_s 

{ 

ULONG pib. 
ULONG pib, 
ULONG pib 
PCHAR pib. 
PCHAR pib. 
ULONG pib 
ULONG pib 

}; 



T 



.ulpid; 
.ulppid; 
_hmte; 
.pchcmd; 
.pchenv; 
Jl status; 
i_uitype; 



struct tib2_s 
{ 

ULONG fib2_uWd; 
ULONG tib2_ulpri; 
ULONG tib2_version; 
USHORT tib2_usMCCount; 
USHORT tib2_fMCForceFlag; 




}; 



struct tib_s 



PVOID tib_pexchain; 

PVOID tibjKtack; 

PVOID tib.pstacklimit; 

PTIB2 tib_ptib2; 
ULONG tib_version; 

PVOID tib ordinal; 
}; 



ppibMyPIB->pib_pchenv 



ppibMyPIB->pib_pchcmd ■ 





Environment 








Command 




Arguments 



LOW 



PTIB ptibMyTIB; 1 
,yPPIB ppihMyPIB^j^f^"' 



DosGetlnfoBlocks t 

SptibMyTIB, sppibMyPIB ); 



HIGH 



Vol 2- 



^JV- ^ TOPI'S 




o 



Searching the Environment 



DosScanEnv (PSZ pszName, <-- ptr to Name string £/*0 

PSZ *ppsz Value );--> ptr to variable to receive ptr to Value (° 



0 NO_ERR0R 
203 ERROR_ENVVAR_NOTJFOUND 

0 Searches the environment for a specified ASCII string (Name). 

0 The Name string must not include the equal (=) character. 

0 Returns a pointer to the value assigned to the environment variable. 




PSZ pszName = "PATH"; 
PSZ pszValue; 



DosScanEnv ( pszName, SpszValue ); 
printf ("Path = %s\n", pszValue) ; 
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Environment Strings 

0 Each process owns a set of environment strings. 

y Each string has the form: <name>-<value> \0. 

0 The last string is terminated with \0\0. 

0 The fully expanded path of the executable file 
follows the last environment string. 

0 Example: 

ice /c /Ss /Ti /W3 /Gs browse.c 



30000 43 4F 4D 53 50 45 43 3D 43 3A 5C 43 4D 44 2E 45 

30010 58 45 00 50 41 54 48 3D 43 3A 5C 3B 43 3A 5C 49 

30020 42 4D 43 32 5C 42 49 4E 3B 00 44 50 41 54 48 3D 

30030 43 3A 5C 3B 43 3A 5C 49 42 4D 43 5C 42 49 4E 3B 

30040 20 00 00 43 3A 5C 49 42 4D 43 32 5C 42 49 4E 49 

30050 43 43 2E 45 58 45 00 



COMSPEC=C: \CMD.E 
XE.PATH=C:\;C:\I 
BMC2XBIN; . DPATH= 
C:\;C: \IBMC\BIN; 

. .C:\IBMC\BIN\I 
CC . EXE . 
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Command Line 



0 Unlike the C compiler, OS/2 does not format the 
command line. 

0 The command (program name) is terminated with \0 

0 The the remainder of the command line is terminated with \0\0 

0 Example: 

C> ice /c /Ss /Ti AV3 /Gs browse.c 

30057 69 63 63 00 20 2F 63 20 2F 53 73 20 2F 54 59 20 ice. /c /Ss /Ti 
30067 2F 57 33 20 2F 47 73 20 42 52 4F 57 53 45 2E 43 /W3 /Gs browse.c 
30077 00 00 
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'C Program Entry State 



main ( int argc , char * argv [ ] , char * erw [ ] ) 

:/ \ \ 

# of arguments pointer to array of pointer to array 

argument strings of environment strings 

0 'C startup code formats the arguments into null-terminated strings. 

0 EXAMPLE: 

C>environ this is a test <cr> 
argc = 5 

argv[0] = "environ" 
argvfl] = "this" 
argv[2] = "is" 
argv[3] = "a" 
argv[4] - "test" 
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DosScan Env Program Example 




Ui §£§ nenv A G — displays the current path 
// ****** os/2 Version 2.x ****** p 

fdefine INCL BASE 
f include <os*,h> 
tinclude <stdio.h> 

#define STDOUT 1 

/ / internal function prototypes 

int terminate ( PSZ pszMsg, APIRET rc, PSZ pszMyName ) ; 
// Globals 

int main (void) 
APIRET rc ; 

PSZ pszMyName = "SCANENV: " ; 

pszName = "PATH" : 
pSzValue; 

nf ^2 = DosScanEnv ( pszName, fcpszValue ): 

if (rc) terminate f'ScanEnv error l\n*J rc, pszMyName), - 

printf ("The current path is - %s\n", pszValue) ; 

return ( NO_ERROR ) ; 

int terminate ( PSZ pszMsg, APIRET rc, PSZ pszMyName) 

CHAR chMsg[255]; 
PSZ pszMlgFUe = "OSO001 .MSG" ; 

ULONG QlMsgEen; 

SP^rc f= % B : & E ?c°f= #% ?) %S W '' P S2M y Name ' rc, pszMsg); 

{ BSSStBKHS [MerTi^iLSSfgfiMSI 5 ^ rC ' ^ Ue ' ^IMsgLen); 
} exit (1); 
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Notes 
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Program Development 



Programming Tools 
Development Process 
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Programming Tools 

0 Include and Header files 

0 Sample Programs 

0 Presentation Manager Utilities 

0 Help Manager Utilities 

0 Message Utilities 

0 WorkFrame/2 
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Header and Include Files 



0 The INCLUDE statement automatically calls a hierarchy 
of header/include files. 

0 The DEFINE/EQU statements are used to control which 
group of functions are included. 

0 Header/include file hierarchy: 



OS2.H (.INC) 

OS2DEF 

BSE 

BSEDOS 

BSESUB 

BSEERR 

BSEDEV 

BSEMEMF 

BSEORD 

BSETIB 

BSEXCPT 



PM 

PMWIN 

PMGPI 

PMDEV 

PMAVIO 

PMSPL 

PMPIC 

PMORD 

PMBITMAP 

PMFONT 

PMDDI 

PMDDIM 



PMERR 

PMHELP 

PMMLE 

PMSEI 

PMSHL 

PMWP 
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OS/2 Development Process 

Source and Include files 



Compiler 
or 

Assembler 



.OBJ 




Static & 
Import 
Libraries 



Module 
Definition 
File (optional) 



,EXE or .DLL 
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OS/2 Linker 



Static Libraries 



Object files 




Import 
Libraries 

Module Definition file 
(optional) 



.EXE or .DLL .MAP 



20DLVP06 92071 1 



6-5 



NMAKE 

Program Maintenance Utility 
0 Automates program development. 

0 Performs only those steps necessary to build the executables. 
0 Example: 

ONMAKE [input file] defaults to MAKEFILE 

browse.exe: 

main.obj: $*.c 

ice /c /Ss /Ti /Kb /Q /Rn $*.c > $*.err 

tool.obj: $*,c 

ice /c /Ss /Ti /Kb /Q /Rn $*.o$*.err 

screen.obj: $*.c 

ice /c /Ss /Ti /Kb /Q /Rn $*.c> $*.err 

browse.exe: main.obj tool.obj screen.obj main.def 
LINK386 IDE /LI /BASE:0xl0000 main tool screen, 

nouns aamo 



Memory Management 



OS/2 Memory Model 
Memory Objects 
Allocation of Memory Objects 
Suballocation of Memory Objects 
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The Flat Memory Model 

0 OS/2 2.x defines a 32-bit memory model that is designed to be portable to 
any 32-bit uniprocessor or multiprocessor architecture including RISC. 

0 The model provides for memory objects that are larger than 64KB or 



larger than physical memory 

0 The 80386/486 processors provide for a paged- virtual memory and 32- 
bit wide segments which may be up to 4GB in size. 

0 The 32-bit segment can be used to simulate a large, flat 32-bit virtual 
address space that is contiguous. 

0 On the 80386/486, a segmented virtual address (16:16 or 16:32) is translated 
by descriptors into a 32-bit (flat) linear address, which in turn is mapped to a 
32-bit physical address by page tables. 

0 A pair of code and data descriptors maps the entire linear address space, 
effectively 'flattening' the virtual address space. 
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Virtual Address Space 

0 In the flat model, a linear address is a virtual address. A virtual address is 
also called a 0:32 address. 

0 The System Virtual Address Space is mapped by a pair of GDT code and 
data descriptors with limit fields of 4GB. 

0 The Process Virtual Address Space is mapped by a pair of GDT code and 
data descriptors with limit fields of 512MB. The 512MB limit provides 
compatibility with 16-bit applications and may be removed in the future, 

0 The process is provided with an independent 512MB linear address space 
by its own set of page directories and page tables. 

0 The virtual address space is partitioned in to private and shared regions. 

0 Private memory is allocated from low addresses toward higher addresses 
and shared memory is allocated from high addresses toward lower addresses. 
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Memory Objects 



v The smallest memory unit in the flat model is a page (4KB). 

0 A memory object is a range of contiguous linear pages within the 
process virtual address space. 

@ All memory objects are addressable simultaneously. 

0 Memory objects are nonrelocatable and, the pages that compose 
objects are swappable. 
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Types of Memory Objects 



Application Code 

Application R/O Data 

Application R/W Data 

Application Allocated 
Private Memory 

Dynamic Link Allocated 
Private Memory 



Application Allocated 
Shared Memory 

Dynamic Link Allocated 
Shared Memory 

Dynamic Link 
Instance Data 

Dynamic Link 
Static Data 

Dynamic Link Code 



Private Address, Shared Storage 
Private Address, Shared Storage 
Private Address, Private Storage 

Private Address, Private Storage 
Private Address, Private Storage 



Shared Address, Shared Storage 

Shared Address, Shared Storage 

Shared Address, Private Storage 

Shared Address, Shared Storage 
Shared Address, Shared Storage 
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DosAllocMem 



DosAllocMem (PPVOID ppb, 
ULONG cb, 
ULONG flag ); 



NO_ERROR 

ERROR_NOT_ENOUGH_MEMORY 
ERROR^INVALIDPARAMETER 
ERROR INTERRUPT 



--> pointer to pointer 
<~ size in bytes 
<- allocation flags 



PAG_READ 0x00000001 
PAG_WRITE 0x00000002 
PAG_EXECUTE 0x00000004 
PAG_COMMIT 0x00000010 
OBJ_TILE 0x00000040 

fPERM (PAG_EXECUTE+PAG_READ+PAG_WRITE) 
fALLOC (OBJ„TlLE+PAG_COMMIT+fPERM) 



PVOID pArray6 ; 

ulAllocFlags=PAG_READ | PAG_WRITE j PAG_COMMIT; 
DosAllocMem ( &pArray6, 0x200, ulAllocFlags ); 
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DosFreeMem 



DosFreeMem ( PVOID pb ); <-- base address of memory object 

*~0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

95 ERROR_INTERRUPT 

487 ERROR_IN V ALID_ADDRES S 



0 Deallocates a private memory object. 

0 For a shared memory object, the reference count is decremented. 
If the resulting count is zero (0), the object is deallocated. 



DosFreeMem { pb ) ; 
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DosQueryMem 



DosQueryMem ( PVOID pb, <-- starting address 

PULONG pcb, <-> size of region 
PULONG pFIag ); ->flags found 



NO_ERROR 
ERROR_NOT_ENOUGH_MEMORYl 
ERROR_INVAHD_PARAMETER 
ERRORINTERRUPT 
ERROR_INVALID_ ADDRESS 



PAG_READ [ 
PAG_WRITE — 
PAG_EXECUTB 
PAG_GUARD 
PAG_COMMIT 
PAG_SHARED 
PAGFREE 
PAG.BASE 



@ Returns attribute information about a range of pages within)th£ process 
virtual address space. 

0 The query terminates at the end of the region or when a noii-nfia'tching 
attribute is detected or when the base page of an object is encountered 



DosQueryMem ( pb, &cb, SFlag ); 



Base 0x00480000 
Base 0x00481000 
Base 0x00490000 
Base 0x00491000 
Base Ox004AOOOO 
Base Ox004A1000 



Length 0x00001000 
Length OxOOOOFOOO 
Length 0x00001000 
Length OxOOOOFOOO 
Length 0x00001000 
Length OxOOOOFOOO 



¥ 11 
10017 



0x00000001 
0x00000002 
0x00000004 
0x00000008 
0x00000010 
0x00002000 
0x00004000 
0x000 I 0000 



Flags 0x000: 
Flags 0x00000007 
Flags 0x00010017 
Flags 0x00000007 
Flags 0x00010013 
Flags 0x00000003 
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DosSetMem 



DosSetMem ( PVOID pb, <-- region address 
ULONG cb, <-- number of bytes 
ULONG flag ); <— access requested 



r o NOJERROR 

5 ERROR. ACCESS_DENIED 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

95 ERROR_INTERRUPT 

212 ERROR.LOCKED 

487 ERROR_INV ALID_ADDRES S 

32798 ERROR_CROSSES_OB.I KCT_ BOU NDARY 



PAG_READ 

PAG_WRITE 

PAG_EXECUTE 

PAG_GUARD 

PAGJTOMMIT 

PAG_J)ECOMMIT 

PAG_DEFAULT 



0x00000001 
0x00000002 
0x00000004 
0x00000008 
0x00000010 
0x00000020 
0x00000400 

fPERM (PAG_EXECUTE+PAG_READ+PAG_ WRITE) 
fSET ( P AG_C OM M I T+P AG_DEC O M M IT +P A G_D£F A U LT +fPERM ) 



@ Sets the attributes of a range of pages within a memory object. 

DosSetMem ( pb, 4096, PAG_COMMIT | PAG_DEFAULT )■ 
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9 



9 





Allocate 
Memory 








Initialize 
Memory for 
Suballocation 










Suballocate 
a Portion of 
the Memory 








Release the 
Suballocated 
Memory 






) 


Release Pool 
Resources 






) 


Release the 
Memory 



Suballocation of Memory 

DosAIlocMem (Ptr, Size, AllocFlags) 

DosSubSetMem (PooIPtr, Flags, Size) 

DosSubAIlocMem (PooIPtr, BlockPtr, Size) 

DosSubFreeMem (PooIPtr, BlockPtr, Size) 

DosSubUnsetMem (PooIPtr) 
DosFreeMem (Ptr) 
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DosSubSetMem 




DosSubSetMem ( PVOID pb, 

ULONG flag, 
\ ULONG cb ); 




<— address of memory pool 
<— suballocated object characteristics 
<-- size in bytes of the pool 



o no_error 

87 ERROR_INVALID_PARAMETER 
310 ERROR_DOSSUB_SHRINK 



DOSSUB_INIT 0x01 
DOSSUB„GROW 0x02 
DOSSUB_SPARSE_OBJ 0x04 
DOSSUB_SERIALIZE 0x08 



0 Initializes, increases in size or enables access by another process to 

the memory pool. The first process does DOSSUBJNIT. 
0 The first 64 bytes are used by the pool manager. 

0 If suballocating between threads in the same process or another process, 
DOSSUB_SERIALIZE will ensure that accesses are serialized. 

0 If the 'parent' object was allocated sparse, DOSSUB_SPARSE_OBJ 
is necessary to have memory committed as necessary. 

DosSubSetMem ( pb, DOSSUB_INIT | DOSSUB_SPARSE_OBJ, 16384 ); 
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DosSubAllocMem, DosSubFreeMem 



/DosSubAllocMem ( PVOID pbBase, 
PPVOID ppb, 
ULONG cb ); 

NO ERROR 
87 ERROR_INVALID_PARAMETER 
311 ERROR_DOSSUB_NOMEM 
532 ERROR_DOSSUB_CORRUPTED 

PVOID pb; 
DosSubAllocMem ( pbBase, &pb, 256 }; 



<— address of memory pool 
~> address of block allocated 
<-- size requested in bytes 



/DosSubFreeMem ( PVOID pbBase, <-- address of memory pool 
PVOID pb, <-- address of block to be freed 

ULONG cb ); <-- size in bytes 

NO_ERROR 
87 ERROR_INVALID_PARAMETER 
312 ERROR_DOSSUB_OVERLAP 
532 ERROR_DOSSUB_CORRUPTED 



DosSubFreeMem ( pbBase, pb, 56 ); 

J0MAPI1292K1H) 
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DosSubUnsetMem 



j DosSubUnsetMem ( PVQID pbBase ); <-- address of memory pool 

0 NO_ERROR 

532 ERROR_DOSSUB_CORRUPTED 



0 Ends the use of a memory pool. 

© Releases the resources used to manage the suballocation of the pool. 

0 Each thread that calls DosSubSetMem must call DosSubUnsetMem 
prior to the memory object being freed. 



DosSubUnsetMem ( pbBase ) ; 



20VWPI1 3 92102a 



7-13 



Notes 
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Introduction to Multitasking 



Serial Multitasking 
Parallel Multitasking 
OS/2 Elements of Multitasking 
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Multiple Tasks 



0 Serial Tasks 

Read a manual 
Answer the phone 
Write a memo 
Create a spreadsheet 
Read electronic mail 
Schedule a meeting 

0 Parallel Tasks 

Drive a car and talk on the phone 
Jog and listen to the radio 

Print a chart, download a data file and format a disk 
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Parallel Multitasking 



0 True parallel multitasking requires multiple processors (CPUs). 

0 Currently, multiprocessor personal computers are rare. 

0 OS/2 is not considered a serial multitasking system. 

0 Preemptive scheduling of tasks gives the effect of parallelism. 
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OS/2 Elements of Multitasking 

SESSIONS 




Manager 

0 Each session is a virtual console device with its own keyboard 
video and mouse buffers. 



0 Switching between sessions usually means switching between 
applications. 
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OS/2 Elements of Multitasking 

PROCESSES 



Personal Information 
Manager 




@ A process is the unit of ownership in OS/2. 

0 Memory, open files and semaphores are system resources 
that are owned by a process. 
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OS/2 Elements of Multitasking 

THREADS 



Personal Information 
Manager 




0 A thread is a unit of work that is dispatched by the scheduler. 
0 Threads share the system resources owned by the process. 
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Thread Management 



Thread Hierarchy 
Creating Threads 
Thread States 
Thread Priority 
Configuration Parameters 
Global, Static and Local 'C Variables 
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Thread Hierarchy 



Session 




Procesfe 



0 A thread is a dispatchable unit of work. 

0 Each process has at least one thread. 

0 A thread owns: 
stack segment 
registers 
priority 
CPUstate 

0 Threads in the same process share page directories and tables. 
0 Threads in the same process are not protected from one another. 
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An Example of Three Threads 



main 0 
{ 



} 

thread A () 
{ 



createthread ( threadA ); 
createthread ( threadfi ); 
suspendthread (main); 



} 

threadB {) 

{ 



while ( 1 ) 
{ 

putchar ("A"); 

} 



while ( 1 ) 

{ 

putchar ( "B" ); 

} 



// do forever 



// do forever 



0 'main* does not call threadA or threadB directly. 

0 Although there are three threads, there is only one process. 
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Another Example of Three Threads 



main () 
{ 

createthread ( threadA , 'A' ); 
createthread ( threadA , 'B' ); 
suspendthread (main); 

} 

threadA (chare) 

{ 

while ( 1 ) //do forever 

{ 

putehar { c); 

i 1 



0 This example shows how 2 threads can execute the same 
code concurrently. 

0 Think of 'A' and 'B' as command line parameters. 

y : Each thread uses the same code, but different data. 
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Thread States 



0 Once created, a thread is in one of these states: 

_ Executing 

- Ready 

- Blocked 

0 Newly created threads may be put in the ready state 
or blocked state depending on the creation parameters. 

0 Only one thread is running at a time. 

0 The scheduler decides which thread will run based 
on the priorities of all threads ready to execute and 
current system load. 
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Priority Classes and Levels 



Class 
Time Critical 



Server 
(Fixed High) 



Regular 



Level 



! High Priority 










D Low Priority 


M 1 



31 

0 
31 



"High Priority 



Low Priority 



High Priority 



Low Priority 





31 


High Priority 




Idle 


0 


Low Priority 


H 1 



@ The initial priority of a thread is inherited from the creating thread. 
0 Each thread in the system is assigned a priority class and a priority level. 
0 OS/2 schedules threads at the same priority in round-robin order. 
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Dynamic Priority Adjustment 



0 Dynamic priority adjustment is the scheduler's ability to alter the priority 
of threads in the regular class. 

0 All threads of the foreground process receive a priority boost. The 
thread performing the user I/O receives an additional boost. 

0 When a thread becomes ready to run as the result of an I/O operation 
completing, the priority is boosted to the highest level in the class. 

0 A thread that is ready to run but, has not executed for the MAX WAIT 
period, is boosted out of its current class to a level just below time critical. 

0 When a thread receives an I/O or starvation boost, its new priority and 
timeslice are retained until the thread executes for a single timeslice. 
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Configuration Parameters Affecting Multitasking 



® THREADS = 64 - 4095 

Controls the number of threads that may be created 

0 TIMESLICE = >=32 [,<65536] 

Specifies the CPU time allocated to each thread 

0 PRIORITY = [ABSOLUTE I DYNAMIC] 

Selects the priority calculation in scheduling Regular 
class threads, 

0 MAXWAIT =1-255 

Specifies the max time a thread must wait for the CPU 
before having its priority boosted. 

0 PRIORITY_DISK_IO = YesINo 

Foreground threads receive disk I/O priority. 
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Thread Management Functions 



DosCreateThread 

DosExit 

DosKillThread 



Thread creation/termination 



DosSuspendThread 
DosResumeThread 

DosEnterCritSec 
DosExitCritSec 



DosGetlnfoB locks 

DosWaitThread 

DosSetPriority 



> Thread suspension/resumption 
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DosGetlnfoBlocks 



DosGetlnfoBlocks ( PTIB *ptib, 

PPIB *ppib); 



— > ptr to ThreadlnfoBlockl 
~ > ptr to ProcessInfoBlock 



struct pibs 
{ 

ULONG pib_ulpid; 
ULONG pib_uippid 
ULONG pibjimte; 
PCHAR 
PCHAR 



pib_pchcmd; 
pib_pchenv; 
ULONG pib_flstatus; 
ULONG pib_ultypc; 



struct tib2_s 
{ 

ULONG tib2_ultid; 
ULONG tib2_ulpri; 
ULONG tib2_version; 
USHORT tib2_usMCCount; 
USHORT tib2_fMCForceFlag; 

}; 



PTIB ptib; 
PPIB ppib; 
TID tid; 

DosGetlnfoBlocks ( Sptib, Sppib ) 
tid = ptib->tib_ptib2->tib2_ultid; 



struct tib_s 
{ 

PVOID tib_pexchain; 
PVOID tib_pstack; 
PVOID tib_pstacklimit; 
— ■ PTIB2 tib_ptib2; 
ULONG tib_version; 
PVOID tib_ordinal; 
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DosCreateThread 



DosCreateThread ( PTID ptid, -> tid of created thread 

PFNTHREAD pfn,<-- function name 
ULONG param, <- 
ULONG flag, < 
ULONG cbstack ); <- 



argument value or reference 
execution flag 
stack maximum size 



0 NOJBRROR 

8 ERROR_NOT_ENOUGH_MEMORY 

95 ERRORJNTERRUPT 

115 ERROR_PROTECTION_VIOLATTON 

164 ERR 0 R_M AX_TH RE AD S_R E AC HED 



0x0 CREATE_READY 

0x1 CREATE_SUSPENDED 

0x0 STACK_SPARSE 

0x2 STACKCOMMITTED 



0 Asynchronous 

0 The specified stack size should include an additional page for 
the guard page. 

0 Initially, only the first two stack pages are committed with the 
second page a guard page unless bit 1 is set in the execution flag. 

0 The function being invoked must be defined with the IBM C Set/2 
'system' linkage. 

void _System readf ile ( PVOID pRead ) ; 

DosCreateThread (stid, (PFNTHREAD) readfile, (ULONG) pRead, 
CREATE_READY | S TAG K_S PARSE , 8192 ); 
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DosEnterCritSec, OosExitCritSec 



DosEnterCritSec ( VOID ); no other thread can run 



0 NCLERROR 

484 ERROR_CRITSEC_OVERFLOW 



OosExitCritSec ( VOID ); other threads may run 



NOJERROR 

484 ERROR_CRITSEC_OVERFLOW 

485 ERROR_CRITSEC UNDERFLOW 
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DosSuspendThread, DosResumeThread 




DosSuspendThread ( TID tid ); <~- threadid 
DosResumeThread ( TID tid ); <-- threadid 



NO_ERROR 
ERROR INVALID THREADID 



0 Threads suspended by DosSuspendThread must be specifically restarted 
with DosResumeThread. 

0 If multiple suspends are issued to the same thread, an equal number of 
resumes must be executed before the thread can be dispatched. 
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DosKillThread 



DosKillThread ( TID tid ); <- id of thread to terminate 



0 NO_ERROR 
170 ERROR_BUSY 
309 ERROR_INVALID_THREADID 



0 May be used without restriction if the application was compiled with the 
subsystem library (/Rn), 



0 It will work with some restrictions with the multitasking libraries (/Gm) 
but, IS NOT RECOMMENDED. 
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DosWaitThread 




DosWaitThread (PTID ptid, 

ULONG option); 

\ 



<--> ptr to tid 
<-- wait options 



NOJ3RROR 
ERROR_INTERRUPT 
ERROR_THREAD_NOT_TERMINATED 
ERROR_INVALID_THREADID 



0 DCWW_WAIT 

1 DCWW_NOWAIT 



@ DosWaitThread will block until a SPECIFIC thread or ANY thread 
in the current process terminates. 

@ If TID=0, wait for any thread to terminate and return that thread's ID, 
otherwise, wait for specific thread. 

APIRET rc = 0; 
TID tid; 

While { !rc } 
< 

tid = 0; 

rc = DosWaitThread ( Stid, DCWW_WAIT ); 
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DosSetPriority 



DosSetPriority ( ULONG scope, 
ULONG class, 
LONG delta, 
ULONG PorTid);\ 



NO_ERROR 

ERROR_INVALID_PROCID 

ERROR_INVALID_PDELTA 

ERROR_NOT_DESCENDANT 

ERROR_INVALID_PCLASS 

ERROR_INVALID_SCOPE 

ERROR_INVALID_THREADID 



-31 PRTYD_M1NIMUM 
31 PRTYD MAXIMUM 



priority scope 
priority class 
priority delta 
Process or Thread ID 



0 PRTYS_PROCESS 

1 PRTYS_PROCESSTREE 

2 PRTYS THREAD 



0 


PRTYC 


.NOCHANGE 


1 


PRTYC_ 


JDLETIME 


2 


PRTYC. 


.REGULAR 


3 


PRTYC. 


TIMECRITICAL 


4 


PRTYC. 


_FOREGROUNDSERVER 



DosSetPriority ( PRTYS_THREAD , PRTYC_NOCHANGE , +5, tid ) ; 
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Mutual Exclusion Problems 



Thread 1 



time 



Creates thread 2 

Opens file 1 
Seeks to record 3 



(suspended) 



Thread 2 
does other processing 

DosSuspendThread (thread 1 ) 

Seeks to record 4 
Reads record 4 
DosResumeThread (threadl ) 



Read record 



0 Which record does thread 1 read? 



20THRO17 920726 



9-17 



Variables in C Programs 



int global; 
main ( ) 
{ 

static int x; // defined in data segment 

int y; // defined on stack 

> 

0 The compiler allocates global and static variables in a data object. 
There is only one copy of each, regardless of how many threads 
are defined. 

0 Variables defined within braces are local variables. The compiler 
defines these on the stack. 

v; Each thread has its own stack. Therefore, each thread will have a 
separate copy of the local variables. 
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Reentrancy with Multiple Threads 



threadA () 




funct_a {) 



A 



H h- 



funct_a 



static intx; 
int y; 



/ 



threadB () 



/ 



for (y=0, x=0, y<50; y++) 
x++; 



B 



/ 



funct_a^; 



0 ThreadA calls funct_a and then is preempted by threadB. 
Assume x=y=25. 

0 ThreadB calls funct_a. A separate copy of 'y' is allocated but, the 
single copy of 'x' is initially cleared. ThreadA preempts ThreadB. 
Assume x=y=30. 

0 ThreadA uses 'x' which is now 30, NOT 25. Funct_a fails! 

0 Serializing access to the static variable through the use of a 
semaphore solves the problem. 
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Reentrancy with C Library Functions 



threadA () 
{ 

printf ("a"); 

} 

thread B () 
{ 

printf ("b"); 

} 



y Several functions in the standard C library are not reentrant. 

0 Access to these functions must be serialized. 

0 The application must perform the serialization if multiple threads 
are created using the DosCreateThread function. 

0 Serialization will be provided by the C run-time library if threads 
are created using the '_beginthread' library function. 
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printF ( ... } 
{ 



// access static 
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beginthread/_endthread C Library Functions 



int _beginthread (void (* _Optlink _thread) (void *),<-- function address 



endthread (void) 

0 _beginthread calls DosCreateThread and then performs thread 
specific initialization in the context of the new thread. 

0 Returns tid if successful or -1 on error 

0 The function invoked must use the default Optlink linkage. 

0 Available in the multithread library (/Gm). 

0 Function prototypes are contained in process. h. 

tid = _beginthread ( readfile, NULL, 8192, (PVOID) &Arg ); 
if ( tid == (TID) -1 ) terminate; 



(void *), 
unsigned, 
void *); 



<-- ignored by C Set/2 
<— stack size in bytes 
<— ptr. to argument(s) 
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DosCreateThread vs _beginthread 



0 DosCreateThread + Subsystem Lib (/Rn) =&) 
® DosCreateThread + Multi-Thread Lib (/Gm) =Q 

@ _beginthread + Multi-Thread Lib (/Gm) =(^) 

1 



DosCreateThread - 
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Synchronization Using Semaphores 



Major Uses of Semaphores 
Classes and Types of Semaphores 

Signaling Events 
Serializing the Access to Resources 
Monitoring Multiple Semaphores 
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Uses of Semaphores 





® 


(fa) 


1 


© 








© 





Signaling 



T4 - 



Serializing 
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Classes and Type of Semaphores 

® Classes: 

Private - accessable by threads in the current process 
Shared - accessable by threads in any process 

0 Types: 

Event - used for signaling 

Mutex - used for serializing 

Mux Wait - used for monitoring multiple Event or 
Mutex semaphores 
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Application of OS/2 Semaphores 



Use 
Serialization 

Signaling 

Serialization 
Signaling 



Scope 



Between threads in 
different processes 

Between threads in 
different processes 

Between threads in 
one process 



Semaphore 
Type 

Named Mutex 
Unnamed shared Mutex 

Named Event 
Unnamed shared Event 

Unnamed Mutex 

Unnamed Event 
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DosCreateEventSem 



DosCreateE ventS em ( PSZ pszName, 

PHEV phev, 
ULONG flAttr, 
BOOL32 fState); 



NO.ERROR 
ERROR.NOT.ENOUGH.MEMORY 
ERROR_INVALID_PARAMETER 
ERROR_INVALID_NAME 
ERROR_DUPLICATE_NAME 
ERROR_TOO_MANY_ HANDLES 



<~ sem name or zero 

--> sem handle 
<-- DC Flags 
<-- initial state 



0x01 DC_SEM_SHARED: 



0x00 
0x01 



FALSE 
TRUE 



0 Named event semaphores (\SEM32\) may be shared between processes by 
default. Unnamed semaphores may be designated as shared. 

0 If the state of the semaphore is false (reset), DosWaitEventSem will block. 

0 If the state of the semaphore is true (posted), the wait function will not block. 

#define POSTED TRUE 
tdefine RESET FALSE 



DosCreateEventSem { "\\SEM32\\MySem" , &hev, 0, RESET ); 

20SEMA06 930206 



10-5 



DosOpenEventSem 




DosOpenEventSem (PSZ pszName, <— sem name or zero 

PHEV phev ); <--> sem handle 



0 NO_ERROR 
6 ERROR_INVALID_HANDLE 
8 ERROR_NOT_ENOUGH_MEMORY 
87 ERROR IXVALID_PARAMETER 
123 ERROR_INVALID_NAME 
187 ERROR_ERROR_SEM_NOT_FOUND 
291 ERROR_TOO_MANY_OPENS 

0 Makes available for use by the calling - process an event semaphore that 
was previously created with the 'share' attribute, 

0 If opening a named event semaphore, the sem handle must be initialized 
to zero prior to the open. 

0 If opening an unnamed event semaphore, the sem handle is the value 
returned from the create function. 



HEV hev = 0; 



DosOpenEventSem ( " \ \SEM32\\MySem" , &hev ); 
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DosCloseEventSem 



DosCloseEventSem ( HEV hev ); <— sem handle 



o NO_ERROR 

6 ERROR_INVALID_HANDLE 

301 ERROR_SEM BUSY 



Q) Decrements the open count for the process. If the open count 
goes to zero (0), the reference count is decremented. 

0 If the resulting reference count is zero (0), the semaphore is 
deleted from the system. 
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DosPostEventSem, DosResetEventSem 

DosPostEventSem ( HEV hev ); <— sem handle 

' o NOERROR 

6 ERROR_INVALID_HANDLE 

298 ERROR_TOO_MANY_POSTS 

299 ERROR_ ALREADY POSTED 



Q) Asserts the specified event semaphore. 

Q) Threads blocked on DosWaitEventSem will unblock. 



/ DosResetEventSem ( HEV hev, <- sem handle 

/_ PULONG pulPostCt ); ~> number of posts 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

300 ERROR_ALREADY_RESET 

0 Negates the specified event semaphore, returns the post count, 
and resets the post count to zero. 

@ Threads issuing a DosWaitEventSem will block. 

DosResetEventSem { hev, SulPostCt ) ; 

5EMAOSS21G2G 
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DosWaitEventSem 



DosWaitEventSem ( HEV hev, <-- event semaphore handle 

ULONG ulTimeout ).; <-- milliseconds 



0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

8 E RR OR_ NOT_ENOU GH JMEM O R Y 

95 ERRORJNTERRUPT 

640 ERROR_TIMEOUT 



SEM_INDEFINITE_WAIT 
SEMJMMEDIATE_RETURN 
or time in milliseconds 



0 If the event semaphore is in the reset (false) state, this function 
will block for the specified amount of time. 

0 If the event semaphore is in the posted (true) state, this function 
returns immediately. 



DosWaitEventSem ( hev, 2000 ); 
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DosQueryEventSem 



Dos Query Events em ( HEV hev, <-- event semaphore handle 

PULONG pulPostCt ); > ptr to returned post count 



0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

87 ERROR_INVALID_PARAMETER 



@ Returns the number of times the semaphore has been posted since 
the last time the semaphore was in the reset state. 

DosQueryEventSem ( hev, fcpuPostCt ); 
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DosCreateMutexSem 



DosCreateMutexSem ( PSZ pszName, 

PHMTX phmtx, 
ULONG flAttr, 
BOOL32 fState); 



NO_ERROR 

ERROR_NOT_ENOUGH_MEM0RY 
ERROR_INVALID_PARAMETER 
ERROR_INVALID_NAME 
ERROR_DUPLIC ATE_N AME 
ERROR_TOO_MANY_HA NDLES 



<— sem name or zero 
— > ptr to handle 
<- create attributes 
<-- initial state 




0x00 


FALSE 


0x01 


TRUE 



0 Named mutex semaphores (\SEM32\) may be shared between processes by 
default. Unnamed semaphores may be designated as shared, 

0 If created in the false state, the semaphore is not owned. 

0 If created in the true state, the semaphore is owned by the creating thread. 
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DosOpenMutexSem 



/ 



DosOpenMutexSem (PSZ pszName, <- sem name or zero 

PHMTX phmtx); <--> sem handle 



0 NCLERROR 

6 ERROR_INVALID_HANDLE 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

105 ERROR_SEM_OWNER_DIED 

123 ERROR_INVALID_NAME 

187 ERROR_ERROR_SEM_NQT_FOUND 

291 ERROR_TOO_M AN Y_OPENS 

0 Makes available for use by the calling process a mutex semaphore that 
was previously created with the 'share' attribute. 

0 If opening a named event semaphore, the sem handle should be initialized 
to zero prior to the open. 

0 If opening an unnamed event semaphore, the sem handle is the value 
returned from the create function. 
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DosCloseMutexSem 



DosCloseMutexSem ( HMTX hmtx ); <-- sem handle 



0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

301 ERROR SEM BUSY 



0 Invalidates the semaphore handle for the current process 
and decrements the reference count. 

0 If the resulting reference count is zero (0), the semaphore 
is deleted from the system. 
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DosRequestMutexSem, DosReleaseMutexSem 



DosRequestMutexSem ( HMTX hmtx, 

ULONG ulTimeout); 



0 NO_ERROR 

6 ERROR JNVALID_HANDLE 

95 ERROR_INTERRUPT 

103 ERROR_TOO_MANY_SEM_REQUESTS 

105 ERROR_SEM_OWNER„DIED 

640 ERROR_TIMEOUT 



It 

V 



<~ semaphore handle 
<— milliseconds 



SEMJNDEFINITE_WAIT 
S EM_1 M MED I A TE_RETUR N 
or time in milliseconds 



DosReleaseMutexSem ( HMTX hmtx ); <-- semaphore handle 



NO_ERROR 
ERROR_INVALID_HANDLE 
ERROR NOT OWNER 



0 If multiple requests are issued from the same thread, a corresponding number 
of releases must be issued to relinquish ownerhip of the semaphore 
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DosQueryMutexSem 



DosQueryMutexSem ( HMTX hmtx, <-- mutex semaphore handle 

PPID ppid, --> ptr to returned PID of owner 

y PTID ptid, -~> ptr to returned TID of owner 

\ PULONG pulCount ); -> ptr to returned request count 

*0 NO_ERROR 
6 ERROR_INVALID_HANDLE 
87 ERROR_INVALID_PARAMETER 
105 ERROR _S EM_OWNER_D IED 



0 The returned PID and TID identify the current owner of the mutex semaphore 
or of the previous owner that terminated without releasing the semaphore. 

0 The request count is the number of requests minus the number of releases. 

PID pid; 
TID iidj 
ULONG ulCount; 

DosQueryMutexSem ( hmtx, &pid, &tid, &ulCount ); 
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CritSec n MutexSem 




CRIl 


IC AL 


SEC 


rioN 


l 

/ 1 


I 

\ 



I 



DosEnterCritSec 
DosExitCritSec 



DosRequestMutexSern ^ 
DosReleaseMutexSem 
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DosCreateMuxWaitSem 



DosCreateMuxWaitSem (PSZ pszName, 

PHMUX phmux, 
ULONG cSemRec, 
PSEMRECORD pSemRec, 



(> 5- 


NOJERROR 


6 


ERROR, 


_INVALID_HANDLE 


S 


ERROR. 


_NOT_ENOUGH_MEMORY 


87 


ERROR. 


.INVALID_PARAMETER 


100 


ERROR. 


_TOO_MANY_SEMAPHORES 


105 


ERROR. 


SEM_OWNER_DIED 


123 


ERROR. 


JNVALID^NAME 


284 


ERROR. 


_DUPLICATE_HANDLE 


285 


ERRORJDUPLICATE_NAME 


290 


ERROR. 


TOO_MA N Y_H ANDLES 


292 


ERROR. 


_WRONG_TYPE 



<~ sem name or zero 
~> sem handle 
<— entry count 
<~ asr structures 
<-- DC flags 



0x01 DC_SEM_SHARED 
0x02 DC M W_W AIT_AN Y 
0x04 DCMW_WAIT ALL 



typedef struct JPSEMRECORD 
{ 

HSEM hsemCur; 
ULONG ulUser; 

} SEMRECORD, * PSEMRECORD; 



0 If both event and mutex semaphores are to be monitored, a separate 
muxwait semaphore must be created for each type. 

0 If the entry count is zero (0), the pSemRec must also be zero (0). 

SEMRECORD SemRecs [ 16 ] ; 

DosCreateMuxWaitSem ( 0, Shmux, 16, SemRecs, DC_SEM_SHARED | DCMW_WAIT_ANY ); 

20SEMA17 931005 
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DosOpenMuxW/aitSem 



DosOpenMuxWaitSera (PSZ pszName, <-- sem name or zero 

PHMUX phmux ); <--> sem handle 



0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

105 ERRQR_SEM_OWNER_DIED 

123 ERROR_INVALID_NAME 

187 ERROR_ERROR_SEM_NOT„FOUND 

291 ERROR_TOO_MANY_OPENS 



0 Makes available for use by the calling process a muxwait semaphore 
that was previously created with the 'share' attribute. 

© If opening a named muxwait semaphore, the sem handle should 
be zero. 

0 If opening an unnamed event semaphore, the sem handle is the value 
returned from the create function. 
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DosCloseMuxW/aitSem 



DosCloseMuxWaitSem (HMUX hmux ); <~ sem handle 



0 NO_ERROR 

6 ERR0R_INVAL1D_HANDLE 

301 ERROR_SEM_BUSY 



® Ends access to a muxwait semaphore for all of the threads 
in the calling process. 

0 When all processes that opened the semaphore have either closed 
it or have ended, the semaphore is deleted from the system. 
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DosAddMuxlA/aitSem, DosOeleteMuxW/aitSem 

DosAddMuxWaitSem ( HMUX hmux, <-- handle of muxwait semaphore 

PSEMRECORD pSemRec );<- ptr to SemRec to add 



0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

100 ERROR_TOO_MANY_SEMAPHORES 

105 ERROR_SEM_OWNER_DIED 

284 ERROR_DUPLICATE_HANDLE 

292 ERROR_WRONG_TYPE 



DosDeleteMuxWaitSem ( HMUX hmux, <-- mux sem handle 

HSEM hsem ); <-- handle of semaphore to be deleted 




NO_ERROR 

ERROR_INVALID_HANDLE 
ERROR_EMPTY MUXWAIT 
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DoslA/aitMuxlA/aitSem 



DosWaitMuxWaitSem (HMUX hmux, 

ULONG ulTimeout, 
PULONG pulUser);/ 



<-- mux sem handle 
<-- milliseconds 
-> from PSEMRECORD 



0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

95 ERRORJNTERRUPT 

103 ERROR_TOO_MANY_SEM_REQUESTS 

105 ERR OR_ S E M_0 W NERJD I ED 

286 ERROR_EMPTY_MU X W AI T 

287 ERROR_MUTEX_OWNED 
292 ERROR_WRONG_TYPE 
640 ERROR_TIMEOUT 



-1L SEM_INDEFINITE_WAIT 
0L SEM_IMMEDIATE_RETURN 
or time in milliseconds 



0 If the muxwait semaphore was created with the WAIT_ANY option, the 
SemRecord is from the semaphore that was posted. If mutex semaphores 
are in the list, the released semaphore will be owned by the caller. 

0 If the W AIT_ALL option was used, the SemRecord is from the last 
semaphore posted. If mutex semaphores are in the list, all will be owned 
by the caller. 

20SEMA21 620722 
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DosQueryMuxWaitSem 



DosQueryMuxWaitSem ( 
HMUX hmux, 
PULONG pcSemRec, 
PSEMRECORD pSemRec, 
PULONG pflAttr ); 



<-- mux sem handle to query 

<--> ptr to max list size 

— > ptr to list of semaphores 

-- > DC flags from DosCreateMuxWaitSem 



o NO.ERROR 

6 ERROR_INVALID_HANDLE 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

105 ERROR_SEM_OWNER_DlED 

289 ERROR_PARAM_TOO_SMALL 



'0x01 DC_SEM_SHARED 
0x02 DCM W_ W AIT_ AN Y 
0x04 DCMW_WAIT ALL 



0 Retrieves the semaphore records from a muxwait semaphore list. 

0 pSemRec points to a buffer that will receive the semaphore records. 

0 On input, pcSemRec points to the max number of records pSemRec 
can hold. On return, it points to the number of records retrieved. 



UL0NG CSemRec - 64; 
SEMRECORD semrec [ cSemRec ] ; 
ULONG flAttr; 



20SEMM2 SOI 095 



DosQueryMuxWaitSem ( hmux, &cSemRec, semrec, SflAttr ); 
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Summary of Semaphore API's 



DosCreateMutexSem 

DosOpenMutexSem 

DosCloseMutexSem 

DosRequestMutex S em 

DosReleaseMutexSem 

DosQueryMutexSem 

Do s CreateE ventS em 

DosOpenEventSem 

DosCloseEventSem 

DosResetEventSem 



DosPo stE ventS em 

Do s WaitE ven tS em 

DosQueryEventSem 

DosCreateMuxWaitSem 

DosOpenMuxWaitSem 

DosCloseMux WaitS em 

DosWaitMuxWaitSem 

DosAddMuxWaitSem 

DosDeleteMuxWaitSem 

DosQueryMuxWaitSem 
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II Notes 
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Timers 



Synchronous Timers 
Asynchronous Timers 
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DosSleep 



DosSleep ( ULONG msec ); <-- interval in milliseconds 



0 NO_ERROR 
322 ERROR_TS_WAKEUP 



Thread Execution 



DosSleep (1000); 



suspended 
! ~ 1 second 



0 Suspends the current thread for a specified time interval. 

0 If the time interval is zero (0), the thread relinquishes the remainder 
of its time slice to another ready thread of equal or higher priority. 
If there is no other ready thread of equal or higher priority, the call 
returns immediately. 
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DosStartTimer 



/DosStartTimer (ULONG msec, < - interval in milliseconds 

HEV hev, <— event semaphore handle 

PHTIMER phtimer ); --> timer handle 

0 NO_ERROR 

323 ERROR_TS_SEMHANDLE 

324 ERROR_TS_NOTIMER 

1 second 1 second 



DosCreateEventSemO 
DosStartTimer{) 



semaphore 
posted by OS/2 



DosResetEventSem (hev) 
by user thread 



0 Starts an asynchronous, repeated-interval timer and post the 
event semaphore each time the interval expires. 



0 The returned timer handle is used with DosStopTimer. 
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DosAsyncTimer 



DosAsyncTimer ( ULONG msec, <-- interval in milliseconds 

HEV hev, <— event semaphore handle 

PHTIMER phtimer ); --> timer handle 



0 NOERROR 

323 ERROR_TS_SEMHANDLE 

324 ERROR_TS_NOTIMER 



Thread Execution 



DosCreateEventSem () 
DosAsyncTimer () 

o 

o 

o 

0 

DosWaitEventSemO 

suspended 



I 

1 second 

I 



: 



0 Starts an asynchronous, single- interval timer and post the 
event semaphore when the interval expires, 

0 The returned timer handle is used with DosStopTimer. 
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DosStopTimer 



DosStopTimer (HTIMER htimer ); <-- timer handle 



0 NO_ERROR 

326 ERROR_TS_HANDLE 



0 Stops either a repeated-interval or single-interval timer. 
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Notes 
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Process Management 

Creating Processes 
Controlling Processes 
Checking Process Status 
Performing Cleanup When a Process Ends 
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Processes 




@ A process is created by the invocation of a particular program 
through the DosExecPgm system call. 

0 Each process has its own memory, threads, file system and inter- 
process communication data structures which isolate it from 
other processes. 

0 Each process is initially created with a single thread. Additional 
threads are created through the DosCreateThread system call. 
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Process Resources 



Environment 

Commandiine 

LDT 

All allocated segments 
File handles 
Pipes 
Queues 



Semaphores 
Threads 
Child processes 
Process ID 

Maximum file handle count 
Default drive, directories 



0 A process is a collection of one or more threads and 
associated system resources. 

0 A unit of ownership. 

0 Can be created at the commandiine by: 

<program name> runs in the current session 

DETACH <program name> runs in the Invalid session 
START <program name> runs in a new session 
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Creating A Process 



Invalid 
Session 




DosExecPgm 




Detached 



0 Processes are created from the command line or under program 
control with the DosExecPgm. 

0 The parent process receives the child process ID number (PID) 
from the DosExecPgm function. 

0 Detached (daemon) processes execute in the Invalid session 

and may not use standard functions to communicate with the user. 
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DosExecPgm 



DosExecPgm (PCHAR pObjname, 
LONG cbObjname, 
ULONG execFlag, 
PSZ pArg, 
PSZ pEnv, 



--> ptr to message buffer 
<— length of message buffer 
<— execution flags 



<-- ptr to argument strings 
<— ptr to environment strings 
PRESULTCODES pRes, --> ptr to result codes buffer 
PSZ pName ); <-- ptr to program file name 



NO_ERROR 

1 ERROR_1NVALID_FUNCTION 

2 ERROR_FILE_NOT FOUND 

3 ERROR_PATH NOT FOUND 

4 ERROR TO MANY_OPEN_FILES 

5 ERROR ACCESS_DENIED 

8 ERROR NOT_ENOUGH_MEMORY 

10 ERROR BAD_ENVIRONMENT 

11 ERROR_BAD_FORMAT 
13 ERROR_lNVAL] D_D AT A 
26 ERROR_NQT_DOS_DISK 

32 ERROR_SHARING_ VIOLATION 

33 ERROR_LOCK_V[OLATTON 

36 ERROR SHARING_BUFFER_EXCEEDED 

m ERROR NO PROC SLOTS 

« ERROR INTERRUPT 

108 ERROR.DRIVE LOCKED 

127 ERROR PROC NOT_FOUND 

182 ERROR_INVALID_ORDlNAL 

190 ERROR 1NVA1.ID_M0DULF.TYPE 

191 ERROR INVALID_EXE_SIGNATURE 

192 ERROR_EXE_MARKED_IN VALID 

195 ERROR_IN VALID MINA1.LOCSIZE 

196 ERR0R_DYNL1NK_FR0M_1NVAL1D RING 



typedef struct _RESULTCODES { 
ULONG codeTerminate; 
ULONG codeResult; 
} RE S ULTC ODES , 
♦PRESULTCODES; 




0 EXEC_SYNC * — 

1 EXEC_ASYNC ^ 

2 EXEC_ASYNCRESULT 

3 EXEC_TRACE 

4 EXEC_BACKGROUND 

5 EXEC_LOAD 

6 EXEC_ASYNCRESULTDB 



Una >i 




DosExecPgm ( Objbuf, 254, EXEC AS YTJC RESULT , 0, 

0, SResc, """readfile.exe" ); 



0 If the process is executed synchronously, codeTerminate and codeResult 

are valid upon return from the function. 
0 If the executed asynchronously, codeTerminate contains the process ID, 
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Process Isolation 




0 Parent and child processes are isolated by separate page tables and directories. 
0 Files and pipes are inherited by the child process. 

0 Parent process can control STDIN, STDOUT, and STDERR file handles. 
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Controlling A Child Process 




0 After starting a child process, the parent can: 
terminate the child 

change the priority of all threads in the child 
test or wait for child completion 
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Process Concurrency 



Start Child 
Process 



Invalid codeTerminate 


NO 


and codeResult 






main () 
{ 

o 

0 

o 
o 

exit (x) 



I 

I } 
l_ 



YES 


Check codeTerminate 




and codeResult 



0 Checking for termination may occur at any time prior to or following the 
'exit ()'. codeTerminate and codeResult are only valid after the 'exit ()'. 
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Command Subtrees 

CX5 




0 DosWaitChild, DosKillProcess and DosSetPriority have two forms: 
ProcessID - only the direct child is affected 
Subtree - the direct child and all descendents are affected 
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Testing for Child Process Termination 



DosWaitChild ( ULONG action, 
ULONG option, 
PRESULTCODES 
PPID ppid, 
PID pid); 



<— which process(s) on which to wait 

<-- method of waiting 

pres,— > ptr to result codes 

— > pid of terminating process 
<— pid of process on which to wait 



0 NO_ERROR 

13 ERROR_INVALID_DATA 

128 ERROR_WAIT_NO_CHILD 

129 E R R O R_CHILD_N OT_CO M PLETE 
184 ERROR_NO_CHILD_PROCESS 
303 ERROR_IN VALID PROCID 



0 DCWW_WAIT 

1 DCWW^NOWAIT 



0 DCWA_PROCESS 

1 DCWA_PROCESSTREE 



0 Waits for completion of a child process whose execution is asynchronous 
to that of its parent process. 

0 The child process is created with the execFlag = EXEC_ASYNCRESULT. 

0 If the child process has multiple threads, the result code returned is the one 
passed by the DosExit request that ends the process. 

DosWaitChild ( DCWA_PROCESS, DCWW_WAIT, &Resc, &pid, Resc .codeTerminate ); 
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DosW/aitChild: 



Process Subtrees 



Action Wait 

Code Option PID 

DCWA_PROCESSTR.EE DCWW.WAIT n 

DCWA_PROCESSTREE DCWW_NOWAIT n 



Action 



Wait until the process subtree has completed and 
then return the direct child's termination code. 

If the process subtree has completed, return the 
direct child's termination code. Otherwise, return 
ERROR_CHILD_NOT_COMPLETE. 

Return Codes: 

ERROR. WAIT_NO„CHILDREN = 128 

ERR 0 R_CH I LD_NOT_C 0M PLETE = 1 29 

NO_ERROR = normal completion; codeTerminate 
and codcRcsult are valid 



0 These will continue to work correctly even if the child process is 
changed to use more/less child processes of its own. 

S0PRCS119JW28 
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DoslA/aitChild: Individual Processes 



Action 
Code 



Wait 
Option 



PID 



DCWA_PROCESS DC WW WAIT 



Action 



Returns as soon as ANY direct child process 
terminates. Returns immediately if child had already 
terminated. 



DCWAJPROCESS DCWW_WAIT 



DCWAJPROCESS DCWW NOW AIT 0 



Returns as soon as the direct child 'n' terminates. 
Returns immediately if child had already terminated. 

Checks for ANY terminated direct child process. If 
one is found, its status is returned, If none found, 
returns ERROR_CHILD_NOT COMPLETE 



DCWA_PROCESS DCWW_NOWAIT n 



Checks the status of direct child 'n'. If terminated, 
returns its status. If still running, returns ERRQR_ 
CHILD NOT COMPLETE. 



0 Use these only if the child process is part of the same application as 
the parent. Parent must know exactly what the child is doing. 
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DosW/aitChild: Process Subtrees 



Action Wait 

Code Option PID Action 



DCWA_PROCESSTREE DCWW_WAIT 0 Wait until ANY direct child and all of its descendants 

have terminated. Selects the subtree of the first 
direct child that terminates. 



DCWA_PROCESSTREE DCWW_NOWAIT 0 Returns error 129 if any process in any subtree is still 

executing. If all subtrees have terminated, returns 
direct child's exit code. To wait for all subtrees , 
repeat call until error code 128 is returned. 
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Performing Cleanup When a Process Ends 



0 For each process, OS/2 maintains a list of procedures 
that it will call when the process terminates. 

0 These procedures get control under the following conditions 

Termination Code Reason 

0 TC_EXIT 

1 TCJHARDERROR 

2 TC_TRAP 

3 TC_KILLPROCESS 

4 TC_EXCEPTION 

0 The termination code is passed as a parameter to the Exit 
List procedure. 
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Exit List Sequence 



main 0 
{ 

DosExitList (0x0100 I EXLSTADD, (PFNEXITLIST) ShutDown); 

o 

0 

o 

0 

exit (0); 

} 

void API ENTRY ShutDown (int TermCode) 

{ 

o 
o 
o 

DosExitList (EXLST_EXIT, 0); 

} 



0 Exit list routines should be short and safe. 

0 The routines can reside in a Dynamic Link Library module. 

0 Ownership of mutex semaphores is transferred to the thread 
performing the exit procedure. 
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DosExitList 



DosExitList ( ULONG ordercode, <— function request code 
PFNEXITLIST pfn ); <- address of handler 



0 NO_ERROR 

1 ERROR_INVALID_FUNCTION 

8 ERROR_NOT_ENOUGH_MEMORY 

13 ERROR_IN VALID DATA 



Low Word.Low Byte: 

1 EXLST_ADD 

2 EXLST_REMOVE 

3 EXLST_EXIT 
Low Word, High Byte: 

Invocation order 



High Word = 0 

0 Defines a routine(s) (EXLST_ADD) to be given control when a 
process completes execution. 

0 Multiple routines with the same invocation order will be executed 
in a LIFO order. 



0 DosExitList with the 'ordercode' = EXLST_EXIT should be the last 
function in the exit list routine. This returns control to the kernel. 



12-16 



Shared Memory Objects 



Named (Global) Shared Memory 
Unnamed (Local) Shared Memory 
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Two Types of Shared Objects 



0 Global (named) 

Use DosAllocSharedMem & DosGetNamedSharedMem. 

Any process that knows the object name may access the 
object (no IPC required). 

0 Private (unnamed) 

Use DosAllocSharedMem and DosGiveSharedMem OR 
DosGetSharedMem. 

Interprocess communication is necessary to pass pointers 
and PID's. 

Accessibility is limited to participating processes. 
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Using Named Shared Objects 



QP rocess Aj) 
mernnatne = \SHAREMEMWIyObj 

// create the shared object and 
// increment the reference count 

DosAllocSharedMem { ppb, memname, size, allocflg); 
o 
o 
o 

// decrement the reference count 
DosFreeMem { pb ); 




mernname = \SHAREMEM\MyObj 

// enable access to the shared object and 
// increment the reference count 

DosGetNamedSharedMem { ppb, memname, flag ); 
o 
o 
o 

// decrement the reference count 
DosFreeMem ( pb ); 



0 Each DosGetNamedSharedMem increments the object's reference count. 
(2) Each DosFreeMem decrements the reference count. 
0 When the reference count = 0, OS/2 discards the object. 

NOTE: Process A & B must synchronize so that Process A does 
not free the object before Process B gets the object. 

fflSWBMOOBHBO? 
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Using Unnamed Shared Objects 




// allocate the object for sharing 
DosAllocSharedMem ( ppb, 0, size, allocflg ); 
// obtain Process B's PID... 



; activate the object for Process B ;/ obtain snared ob j ect 

DosGiveSharedMem ( pb, pid, flag ); 11 P ointer v, a IPC 
; pass the pointer to Process B 

; using IPC // access the object 

; release the object // release the object 

DosFreeMem { pb ); DosFreeMem ( pb ); 



0 Each DosGiveSharedMem ( DosGetSharedMem ) increments the 
reference count. 

0 As with named objects, when the reference count = 0, OS/2 
discards the object. 

NOTE: Process B could use DosGetSharedMem instead. Process A 
must still pass the pointer to Process B. 
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DosAllocSharedMem 



I DosAllocSharedMem ( PPVOID ppb, 
/ PSZ pszName, 

/ ULONG cb, 

f ULONG flag); 

l 0 NOJERROR 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

95 ERROR_INTERRUPT 

123 ERRORJNVALID_NAME 

183 ERROR_ALREADY_EXISTS 



PAG_COMMIT 0x00000010 
OBJ_TILE 0x00000040 
OBJ_GETTABLE 0x00000100 
OBJ_GIVEABLE 0x00000200 

fPERM ( P A G J2 XEC UTE+ P A G _RE A D+ P A G_ W RITE) 

fSHARE (OBJ_GETTABLE+OBJ_GIVEABLE) 

f ALLOCS HR (OBJ_TILE+PAG_COMMIT+fSHARE+fPERM) 



— > address pointer 
<— name or zero 
<~ size in bytes 
<— allocation flags 



PVOID pArray3 ; 

PSZ pszName = "WsharememWMyQbj " ; 

ULONG ulAllocFlags = PAG_READ | PAG_WRITE j PAG_COMMIT; 
DosAllocSharedMem ( &pArray3 r pszName, 0x20000, ulAllocFlages ); 
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DosGetNamedSharedMem 



DosGetNamedSharedMem (PPVOID ppb, 

PSZ pszName, 

ULONG flag); 



—> address pointer 
<— name 

<~ access requested 



NO_ERROR 

ERROR_FILE_NOT_FOUND 

ERROR_NOT_ENOUGH_MEMORY 

ERROR_INVALID_PARAMETER 

ERROR_INTERRUPT 

ERROR_INVALID_NAME 

ERROR LOCKED 



PAG_READ 
PAG _ WRITE 
P AG_EXEC UTE 
PAG GUARD 



0x00000001 
0x00000002 
0x00000004 
0x00000008 



fPERM (PAG_EXECUTE+PAG_READ+PAG_WRITE) 
fGETNMSHR (fPERM) 



0 Enables access to a named memory object that was allocated by 
DosAllocSharedMem. 

0 The initial call by a process to this function increments the object's 
reference count. 

@ At least one process must call this function prior to the allocating process 
calling DosFreeMem, else the memory object will be released. 

PSZ pszMemName - " \\sharemem\ \MyOb j " ; 
PVOID pArray3 ; 



DosGetNamedSharedMem { S,pArray3 , pszMemName, PAG READ ); 



20SKBM06 S30SSB 



13-6 



DosGiveSharedMem 



DosGiveSharedMem (PVOID pb, 

PID pid, 
ULONG flag ); 



0 


NOERROR 


5 


ERROR 


_ ACCES S ..DENIED 


8 


ERROR 


.NOT_ENOUGH MEMORY 


87 


ERROR. 


_INVALID_PARAMETER 


95 


ERROR 


.INTERRUPT 


212 


ERROR. 


.LOCKED 


303 


ERROR 


INVALID_PROCID 


487 


ERROR. 


.INVALID_ADDRESS 



<~ identify by address 
<-- PID of recipient 
<— recipient access rights 



PAG_READ 
PAG_ WRITE 
PA G_EXECUTE 
PAG_GUARD 



0x00000001 
0x00000002 
0x00000004 
0x00000008 

fPERM (PAG_EXECUTE+PAG_READ+PAG_WRITE) 
fGIVESHR (fPERM) 



0 Gives another process access to an unnamed memory object allocated 
'giveable' with DosAllocSharedMem. 

0 The initial call by a process to this function increments the object's 
reference count, 

DosGiveSharedMem ( pb, pid, PAG_READ | PAG_WRITE ) ; 
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DosGetSharedMem 



DosGetSharedMem ( PVOID pb, 

ULONG flag); 



< - identify by address 
<-- access flags 



0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

95 ERROR_INTERRUPT 

212 ERROR_LOCKED 



PAG_READ 
PAG_WRITE 
PAG_EXECUTE 
PAG GUARD 



0x00000001 
0x00000002 
0x00000004 
0x00000008 



fPERM (PAG_EXECUTE+PAG_READ+PAG_ WRITE) 
fGETSHR (fPERM) 



0 Enables access to an unnamed memory object that was allocated 'gettable' 
with DosAllocSharedMem. 

0 The initial call to this function by a process increments the object's 
reference count. 

0 At least one process must call this function prior to the allocating process 
calling DosFreeMem, else the memory object will be released. 

DosGetSharedMem ( pb, PAG_READ | PAG_WRITE ); 

20SHH™ 
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File Input/Output 



OS/2 File Systems 
Opening/Creating/Accessing Files 
Standard and Extended File Attributes 
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OS/2 File Systems 



File Name 



open 



handle 



read write seek 



handle 



close 



0 Applications use file systems to manage storage devices. 
0 To an application, files are logical sequences of data. 

(2) File systems manage the physical location of data on the 
storage device. 

0 A connection must be established with the file or device 
to perform input/output. 
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Multiple File Systems 

User 

I 

Standard File I/O Function 

OS/2 File System Request Router 

i 1 

FAT IFS 

I 1 
Drive A: Drive F: 

0 OS/2 supports the coexistence of mulitple file systems: 
OS/2 FAT file system similar to DOS (default) 
Installable File Systems (IFS) 

0 Each logical device may be managed by a different file system. 

0 A File System Driver (FSD) must be loaded for each file system 
other than the FAT system. 

0 The FSD is installed via the IFS statement in CONFIG.SYS. 

0 The device is managed by the file system used to format the device. 
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Recognizing DOS and OS/2 Files 



DOS 




QS2FATy 



OS/2 



0 OS/2 recognizes files created by: 

DOS FAT file system 
OS/2 FAT file system 
Installable File Systems 

@ DOS recognizes files created by: 

DOS FAT file system 
OS/2 FAT file system 

0 The primary partition must be FAT for dual-booting. 
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Naming OS/2 Files 



0 FAT File Systems: 

8 character file name 
3 character extension 
Names are case insensitive 

0 Installable File Systems: 

Each element of a full path name may be a max of 254 characters. 
Names are not case sensitive, but case is preserved. 
Blanks in the middle of a file name are significant. 
Additional legal characters for file names +-;,[] 

This . f ile . name . would . have . been . longer .but, . I .got . tired. of . typing 
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Using Long File Names 



0 Programs that can handle long file names are marked as 
being 'long-name-aware'. 

v This is done with the Module Definition File by including the 
NEWFILES statement. 

0 For compatibility, DLL's should not use or return long file names. 

0 Files with long names may be moved to non-IFS disks using 
the File Manager. 

0 The file name will be truncated to a max of 1 1 characters and 
the original long name will be stored in an Extended Attribute. 

0 When copied back to an IFS drive, the long name will be restored. 
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Opening/Creating Files 



0 A file must be opened before it can be accessed. 

0 The DosOpen function will open an existing file or create 
a new file. 

0 The file is opened/created by name and a file handle is returned. 

0 The handle is used to reference the file in other file system 
functions. 

0 When open/creating a file, the caller specifies how the file will 
be accessed and how it will be shared with other processes. 



Access Mode 
Read Only 
Write Only 
Read/Write 



Deny All (no sharing) 
Deny Read 
Deny Write 

Deny None (full sharing) 



Share Mode 
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DosOpen 




DosOpen (PSZ pszFileName, 
PHFILE pHf, 
PULONG pulAction, 
ULONG cbFile, 
ULONG ulAttribute, 
ULONG fsOpenFlags, 
ULONG fsOpenMode, 
PEAOP2 peaop2 )\ 



<— file name 

--> ptr to returned file handle 

--> ptr to returned action taken 

<— size in bytes for create or replace 
<— file attributes — 

<-- open flags 

<— open mode 
<— ptr to EA structure 



NO_ERROR 
ERROR_FILE_NOT FOUND 
ERROR.PATH NOT_FOUND 
ERROR TOO MANY_OPEN_FILES 
ER RO R - A CC ES S _D ENIED 
ERROR_IN VALID ACCESS 
ERROR _NOT_DO S_D I S K 
ERROR_SHARING_ VIOLATION 
E R RO R _S H AR I N G_B UFFER_EXCEED ED 
ERROR_CANNOT MAKE 
ERROR_IN VALID. .PARAMETER 
ERROR_DEVlCE_IN_USE 
ERROR_DRIVE_LOCKED 
ERROR_OPEN_FAII.ED 
ERROR_DISK_FULL 
ERROR_FILENAME EXCED RANGE 
ERROR_PIPE_BUSY 



0x0000 


OPEN 


0x0001 


□ PEN 


0x0002 


□ PEN 


0x0010 


OPEN 


0x0020 


OPEN 


0x0030 


OPEN 


0x0040 


OPEN 


0x0080 


OPEN 


oxoooo 


OPEN. 


0x0100 


OPEN 


OxU200 


OPEN. 


(WBon 


OPEN 


Ox 1000 


OPEN. 


ti\ia>> 


OPEN 


0x4000 


OPEN. 


0x8000 


OPEN 




I Oxl FILE_EXISTED 



0x2 


FILE 


CREATED 


0x3 


FILE. 


REPLACED 


W) 


FILE 


NORMAL 


Ox] 


FILE. 


.READONLY 


(W 


1-ll.li 


HIDDEN 


!t.<S 


FILE 


SYSTEM 


OxlO 


FILE 


DIRECTORY 


(k20 


FILE 


ARCHIVED 



0x00 
0x10 



OPEN _ ACTION _F A1L_IF_EX ISTS 
OPEN _ ACTIGN_OPEN_] F_EX] STS 
OPEN.ACTION_REPLACE_lF_EXISTS 

OPEN ..ACTION_FA!LJF_ NEW 

O PEN_ ACTI ON_CRE ATE_I F_NE W 



DosOpen ( "TestFile" 



&H£, SulAction, 0, FILE NORMAL , OPEN ACTION OPEN IF EXITS , 
OFEN_ACCESS_READONLY 1 OPEt^SHARE_D"ENYWRITE", 0 ) ; 
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Synchronous File Input/Output 



IDosRead [Write] ( HFILE hFile, <-- open file handle 

PVOID pBuffer, <-- ptr to data buffer 

ULONG cbRead [Write], <-- # of bytes to transfer 
PULONG pcb Actual ); --> ptr to returned actual bytes 

0 NOJBRROR 

5 ERROR_ACCESS„DENIED 

6 ERROR_INVALI D_H ANDLE 
19 ERROR_WRITE_PROTECT 
26 ERROR^NOT_DOS_DISK 

29 ERROR_WRITE_FAULT 
33 ERROR_LOCK_VIOLATION 
109 ERROR_B ROKEN_PIPE 
234 ERROR_MORE_DATA 

0 DosRead (Write) automatically moves the file pointer. 

0 Reading and writing 512 bytes at a time (sector size) will 
speed up the processing 

0 If read returns cb Actual = 0, end of file was reached. 

0 Standard device handle values: 

0= STDIN 1 = STDOUT 2 = STDERR 
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Asynchronous File Input/Output 



typedef struct _RW 

[hfILE hRle; 
PVOID pBuffer; 
ULONG cb; 
PULONG pcbActuaf; 
APIRET re; 
HEV hev; 
} RW, *PRW; 

int main ( void ){ 
RW rw; 

DosCreateEventSem {); 

DosCreateThread ( ptid, AsyncRW, &rw, ready, 16384 ); 

Other Processing 

DosWaitEvenlSem ( ) 
if (rw.rc) terminate; 

Data is Valid 
} 



AsyncRW ( PRW prw ) 

{ 

prw->rc = Dos Read ( prw->hFile, 

prw->p Buffer, 
prw->cb, 
prw->pcbActual ); 

DosPostEventSem (); 
} 



0 The event semaphore is posted when the read or write is completed. 

(v$ main must wait until the semaphore is posted to access the data 
in the buffer. 
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Changing the Size of a File 



DosSetFileSize (HFILE hFile, <-- open file handle 
ULONG cbSize );<-- size in bytes 



o NCLERROR 

5 ERROR_ACCESS_DENIED 

6 ERROR_INVALID_HANDLE 
26 ERROR_NOT_DOS_DISK 

33 ERRQR_LOCK_VIOLATION 

87 ERROR_INVALID_PARAMETER 

112 ERROR DISK FULL 



0 Changes the amount of space allocated to a file. 

0 The file must be opened for write access. 

0 The file can be truncated or extended in size. If extended, 
the value of the new bytes is undefined. 

DosSetFileSize ( hf, 50000 ); 



20FILE11 921021 



14- n 



Inheriting Files 




0 If the parent opens a file with the inheritance option, then that file 
handle may be used by the child process. 

0 All sharing and access modes are preserved. 

0 Processes own files, threads do not. Any thread in a process can 
read from a file, even if it is not shared. 
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Locking Regions of a File 



DosSetFileLocks ( HFILE hfile, <~ open file handle 

PFILELOCK pflUnlock, <-- ptr to unlock range 
PFILELOCK pflLock, < - ptr to lock range 



ULONG timeout, 
ULONG flags ); 



<~ time in milliseconds 
<-- atomic/share flags 



NO_ERROR 
6 ERROR_INVALID_HANDLE 
33 ERROR_LOCK_VIOLATI0N 
36 ERROR_SHARING_BUFFER_EXCEEDED 
87 ERROR_INVALID_PARAMETER 
95 ERROR_INTERRUPT 

174 ERROR_ATOMIC_LOCK_NOT_SUPPORTED 

1 75 ERROR_READ_LOCKS_NOT_SUPPORTED 




_typedef struct _FILELOCK { 

LONG lOffset 

LONG IRange 
} FILELOCK, *PFILELOCK 



1 0x1 Share for read-only 
! 0x2 Atomic lock 



0 A process may temporarily be prohibited from accessing certain 
areas of a file that was opened for sharing by another process. 

0 If processes are not accessing the same region at the same time, 
they both operate in parallel. 

0 Locked regions are not inherited from the parent process. 

FILELOCK filelock; 
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filelock. lOf f set = 1500; 
filelock. IRanqe = 250f 
DosSetFileLocks { hFile, 



0, Sfilelock, 300, 0 ); 
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Updating File Data/Directory 




DosClose ( HFILE hFile ); <-- open file handle 



DosResetBuffer ( HFILE hFile ); <- open file handle 



0 NOJBRROR 



2 ERROR_FILE_NOT_FOUND 

5 ERROR, ACCESS_DENIED 

6 ERROR_INVALID_HANDLE 



0 DosClose flushes the internal buffers, updates the directory 
and invalidates the file handle for the calling process. 

v DosResetBuffer flushes internal buffers and updates thedirectory 
without closing file. If the file handle OxFFFF is specified, all 
buffers for all files open to the process are flushed. 
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Standard File Attributes 



Date and Time of Creation 
Date and Time of Last Access 
Date and Time of Last Write 
File Size 

Allocated File Size 
File Attributes 



0 This is referred to as Level 1 File Information.. 

0 The DIR command displays a subset of this information. 

0 An application may request Level 1 information with the 
DosQueryFilelnfo or DosQueryPathlnfo functions. 
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Extended File Attributes 

0 Extended Attributes (EAs) may be used to describe a file to 
another application, the operating system or the file system. 

0 EAs may be used for such things as: 

Store notes such as the creator of a file 
Catagorize files such as source, icons, bit maps, etc. 
Describe the format of data in a file 
Append additional data to a file 

0 EAs are not part of the file data but, are maintained by the file system. 

0 More than one EA may be associated with a file. 

0 Each EA consist of an ASCII Name and a Value of any data type. 

0 The maximum size of each EA is 64Kb. 

0 EAs are classified as critical or non-critical. 
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Naming Extended Attributes 



0 Application specific EAs should be prefixed with the company 
name and product name. 

Company - IBM 

Product - DisplayWrite 

Attribute - Stuff 

EA Name = IBM_DW. Stuff 

0 A set of Standard Extended Attributes (SEAs) define common 
info associated with a file. 

0 SEA names are prefixed with a period (.). 

.TYPE 

.KEYPHRASES 

.SUBJECT 

.COMMENTS 

.HISTORY 

.VERSION 

.LONGNAME 

.ICON 

.ASSOCTABLE 
.CODEPAGE 

0 Reserved prefixes are $ @ & + 
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Extended Attribute Data Types 



Description 


Data Type 


Constant 


Length-preceded binary 


FFFE 


EAT 


.BINARY 


Length-preceded ASCII 


FFFD 


EAT 


.ASCII 


Length-preceded bitmap 


FFFB 


EAT 


.BITMAP 


Length-preceded metafile 


FFFA 


EAT. 


.METAFILE 


Length-preceded icon 


FFF9 


EAT. 


.ICON 


ASCII EA name of associated data 


FFEE 


EAT. 


EA 


Multi-valued, multi-typed data 


FFDF 


EAT. 


MVMT 


Multi-valued, single-typed data 


FFDE 


EAT_ 


MVST 


ASN.l field 


FFDD 


EAT. 


ASN1 


Reserved 


8000- 
FFDC 






User-definable 


0000- 
7FFF 







0 The Value of an EA may be any type of data. 

0 The first word of the EA data should indicate the data type. 
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Extended Attribute Data Structures 



EA0P2 Structure 



Pointer to 


Pointer to 


Error 


GEA2Ust 


FEA2Ust 


Offset 



GEA2List Structure 


Length of 
GEA2List 


GEA2 


GEA2 




GEA2 



GEA2 



ULONG oNextEntryOffset 
BYTE cbName 
CHAR szName[1] 



FEA2List Structure 



Length of 
FEA2List 


FEA2 


FEA2 




FEA2 




FEA2 




) 

/ 



ULONG oNextEntryOffset 



BYTE fEA (critical flag) 
BYTE cbName (length of name) 
USHORT ebValue (length of value) 
CHAR szName[1] 

EA data type 

EA data length 



EA value data 
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Example of a Single- Value EA 



ULONG oNextEntryOffset = 25; 

BYTE f EA =0; // non-critical 

BYTE cbName =5; // length of name 

USHORT cbValue =11; // length of value 

CHAR szName[] = ".TYPE"; // EA name 

USHORT us Type = EAT_ASCII; // data type 

USHORT cbData =6; // length of data 

CHAR cData[] = "C Code"; 
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Example of a Multi-Value, Single-Type EA 



ULONG 

BYTE 

BYTE 

USHORT 

CHAR 

USHORT 

USHORT 

USHORT 

USHORT 

USHORT 

CHAR 

USHORT 

CHAR 

USHORT 

CHAR 
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oNextEntryOf f set = 56; 

fEA =0; // non-critical 

cbName =16; // length of name 

cbValue =31; // length of value 

SzName[] = "PCRI_SAMPLE .MVST" ; // EA name 

US Type = EAT__MVST ; 

usCodePage =0; // use default 

usNumEntries =3; // number of entries 

usDataType = EAT_ASCII; 

cbDatal =5; // length of 1st entry 

cDatal[ ] = "Hello"; 

cbData2 = 4; 

cData2[ ] - "OS/2" ; 

cbData3 =5; 

cData3[] = "World"; 



Example of a Multi-Value, Multi-Type EA 



ULONG 

BYTE 

BYTE 

USHORT 

CHAR 

USHORT 

USHORT 

USHORT 

USHORT 

USHORT 

CHAR 

USHORT 

USHORT 

BYTE 



oNext Ent ryO f f s e t = 55; 

f EA =0; // non-critical 

cbName =16; // length of name 

cbValue =30; // length of value 

szNamef] = " PCRI_S AMPLE. MVS T" ; // EA name 

usType = EAT_MVMT; 

usCodePage =0; // use default 

usNumEntries =2; // number of entries 

usDataType = EAT_ASCII; 

cbDatal = 11; // length of 1st entry 

cDatal [ ] = "Hello World"; 

usDataType = EAT_BINARY; 

cbData2 = 4; 

bData2[4] - {0x68, 0x65, 0x6c f 0x6f}; 
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Preserving EAs 



0 Non-EA aware programs may not open files with CRITICAL EAs 
except for replacement. 

0 Files with non-critical EAs may be accessed by non-EA aware 
programs. 

0 E A- aware programs do not have any restrictions. 

0 EAs may be lost when files are: 

Transferred to a down-level system 

Opened for replacement by non-EA aware programs 

Sent over comm lines 

0 The EAUTIL program allows EAs to be handled separately from 
the associated file. 

0 EAs may be stripped and placed in a separate file and then 
reattached to the associated file. 
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Managing EAs 



0 EAs may be defined when a file/subdirectory is created with 
DosOpen/DosCreateDir. 



0 EAs may be defined for existing files with DosSetFilelnfo or 
DosSetPathlnfo. 

0 EAs may be examined with DosQueryFilelnfo, DosQueryPathlnfo 
or DosEnumAttribute. 



0 Files with specific EAs may be searched with DosFindFirst 
and DosFindNext 
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Queues 



Creating/Peeking/Reading Queues From A Server Process 
Opening/Writing/Closing Queues From A Client Process 
Monitoring Multiple Queues From A Server Process 
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Queue Overview 



Client Process 



DosOpenQueue (...) 
Dos AllocS haredMem(..,) 
DosGiveSharcdMcm ( ... ) 
;copy data to object 
DosWriteQueue (...) 
DosFreeMem (...) 
DosCloseQueue ( ... ) 



\QUEUES\MYQUEUE 



Request 


PID 


DataLength 




Data Address 




Element Priority 





Server Process 



DosCreateQueue ( ... ) 
DosReadQucue (...) 
DosFreeMem ( ... ) 
DosCloseQueue ( ... ) 



0 Only the queue creator may read the queue. 

0 The Client process allocates the shared object and passes the 
pointer and size to the Server process through the queue. 

0 You could also use 'named' shared objects and the suballocation 
API's instead of DosGiveSharedMem. 
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DosCreateQueue 



DosCreateQueue (PHQUEUE phq, 
ULONG priority, 
PSZ pszName ); 



o NO_ERROR 

87 ERROR_INVALID_PARAMETER 
332 ERROR_QUE_DUPLICATE 

334 ERROR_QUE_NO_MEMORY 

335 ERROR_QUE_INVALID_NAME 



-> r/w queue handle 
<- QUE_ constants 
<- 



\QUEUES\. 



OL QUE_FIF0 

1L QUE_LIFQ 

2L QUE_PRIORITY 

4L QUE_CONVERT_AD DRESS 



0 The process creating a queue is the server. 
0 Processes opening the queue are clients. 

HQUEUE hq; 

DosCreateQueue ( shq, QUE_LIFO, "WqueuesWMyQue" ); 
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DosOpenQueue 



ZDosOpenQueue ( PPID ppid, -> pid of server 

PHQUEUE phq, -> write queue handle 
PSZ pszName ); <- \QUEUES\... 

U NO_ERROR 

334 ERROR_QUE_NO_M EMORY 

341 ERROR_QUE_PROC_NO_ACCESS 

343 ERROR_QUE_NAME_NOT_EXIST 



0 Enables access to a previously created queue. 



DosOpenQueue ( Spid, &hq f " WqueuesWMyQue" ); 
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DosW/riteQueue 



DosWriteQueue ( HQUEUE hq, <- queue handle 

ULONG request, <- 32-bit application specific 
ULONG cbData, <- data size 
PVOID pbData, <- data pointer 
ULONG priority ); <- priority value, 15=high, O=low 



0 NO_ERROR 

334 ERROR_QUE„NO_MEM OR Y 

337 ERROR_QUE_INV ALID_H ANDLE 



RD 

request 
cbData 
pbData 
priority 



DosWriteQueue ( hq, Oxlff, 2000, pBuffer, 0 ) ; 
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DosPeekQueue 

DosPeekQueue ( HQUEUE hq, <- queue handle 

PREQUESTDATA pRequest,-> clients pid and request — i 



PULONG pcbData, 
PPVOID ppbuf, 
PULONG element, 

BOOL32 no wait,, 
PBYTE ppriority,^ 
HEV hsem); 



0 NO_ERROR 

87 ERROR_INVALID_PARAMETER 
330 ERROR_QUE_PROC_NOT_OWNED 
333 ERROR_QUE_ELEMENT_NOT_EXIST 
337 ERROR_QUE_INVALID_HANDLE 
342 ERROR_QUE_EMPTY 
433 ERROR_QUE_INVALID_WAIT 
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-> data size 
-> data address 
<-> 0 input, peek 1st element 
N output, specific element 
<- DCWW_ parameter 
-> priority value 
<- event semaphore handle 



typedef struct _REQUESTDATA 

i 

PID pid; 
ULONG ulData; 

} REQUESTDATA, * PREQUESTDATA ; 



'0 DCWW_WAIT 
1 DCWW NOW AIT 



N 

0 



300 



DosPeekQueue ( 
QueueHandle, 
^Request, 
SiDataLength, 
SDalaAddfess, 
ScElementCode, - 
DCWW.NOWATT, 
AHementPriortty, 
SemaphoreHandle ); 



900 



903 



902 



904 



901 



905 



OUT 
900 



903 



906 
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DosReadQueue 



DosReadQueue ( HQUEUE hq, 

PREQUESTDATA 
PULONG pcbData, 
PPVOID ppbuf, 
ULONG element, 
BOOL32 wait, 
PBYTE ppriority,' 
HEV hsem); 



<- 

pRequest, 
> 
-> 
<- 
<- 
-> 
<- 



0 NO_ERROR 

87 ERROR_INVALID_PARAMETER 
330 ERROR_QUE_PROC_NOTJ3WNED 
333 ERROR_QUE_ELEMENT_NOT_EXIST 
337 ERROR_QUE_INVALID_HANDLE 
342 ERROR_QUE_EMPTY 
433 ERROR_QUE_INVALID_WAIT 



queue handle 

-> clients pid and request 

data size 

data address 

element code 

DCWW_ parameter 

priority value 

event semaphore handle 



typedcf struct _REQUESTDATA 

PID pid; 
ULONG ulData; 

} REQUESTDATA, *PREQUESTDATA; 



0 DCWW_WAIT 

1 DCWW_NOWAIT 



DosReadQueue ( hq, ^Request, &cbData, &pbuf, 0, DCWW_NOWAIT f &pri, hev ); 
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DosQueryQueue, DosPurgeQueue, DosCloseQueue 



DosQueryQueue (HQUEUE hq, <- queue handle 

PULONG pcbEntries ); -> number of queue elements 



0 NO_ERROR 

337 ERROR_QUE_INVALID_HANDLE 



DosPurgeQueue (HQUEUE hq ); <- queue handle 



0 NO_ERROR 

330 ERROR_QUE_PROC_NOT_OWNED 
337 ERROR_QUE_INVALID_HANDLE 



DosCloseQueue (HQUEUE hq ); <- queue handle 



0 NO_ERROR 

337 ERROR_QUE_INVALID_HANDLE 
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Monitoring Mutiple Queues 



SERVER 
PROCESS 




0 Allows the monitoring of multiple queues by the server process. 

0 When a client writes to the queue, the event semaphore will 
automatically be opened and posted. 

0 The server could query the event semaphore to determine the 
number of posts issued. 



£0qucsQ9fl20S-C 



15-9 



Notes 
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Dynamic Link Libraries 
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Static Linking 
Dynamic Linking 
Building a Dynamic Link Library 
Dynamic Linking at Run Time 
DLL Initialization 
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Static Unking 



Object Files 



Libraries 



.OBJ 


.OBJ 




.LIB 


.LIB 



LINK386 



.EXE 



0 All object file and library file code and data are in the .EXE 
even if not all will be used. 
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Disadvantages of Static Linking 



0 All of the target code and data must be available at link time. 

0 All modules must be re-linked if the target code changes. 

0 The target code can not be shared among applications. 

0 The operating system may have multiple copies of the same 
code/data in memory and on the disk. 

0 The executable (.EXE) files are large. 
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Advantages and Disadvantages of Dynamic Link Libraries 

0 Advantages: 

OS/2 only keeps one copy of the code in memory. 
Upgrades are easier; simply replace the DLL. 
Dynlink procedures can call other dynlink procedures. 
.EXE files are smaller. 

0 Disadvantage: 

Program loading may take longer. 
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Dynamic Links vs Processes 



0 OS/2 views dynlinks as subroutines, not as separate 
processes. 

0 The dynlink procedure runs in the context of its 
calling thread and process . 

0 Dynlink calls are fast since there is no change in 
the privilege level. 

0 Dynlink objects are mapped to the same linear addresses 
for all processes. 
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APP.OBJ 



EXTRN fillstr 
call fillstr 



APP.EXE 



IMPORT util.fillstr 
call fillstr 



Dynamic Linking 




LINKER 




UTILLIB 



fillstr; 
MODULE UTIL 
ENTRY fillstr 



0 The program makes an external reference to a procedure: 

EXTERN USHORT APIENTRY fillstr (PSZ pszBuff, USHORT usLength, CHAR chFill); 

0 The object file is linked to a special library file that contains the 
module name where the procedure 'fillstr' lives (UTIL). 

0 The APP.EXE file does NOT contain the target Code or Data. 
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Load Time 



APP.EXE 



IMPORT util.fillstr 
call fillstr 



UTILDLL 




fillstr 0 




return (); 



LOADER 



0 The OS/2 loader brings in the target code and fixes 
up the call. 

@ 'fillstr' runs as a near procedure. 

0 The Dynamic Link Library file (DLL) contains the code 
for 'fillstr'. 
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Building a DLL 



@ A program, LODTMDLL, will call the procedure FILLSTR 
which is in the Dynamic Link Library UTIL.DLL. 

® FILLSTR expects a pointer to a buffer, the length of the buffer 
and the character with which to fill the buffer. 
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Preparing the .DLL and Import Library 



UTILC 



void fillstr (pszString) 

{ 
} 



UTILOBJ 



PUBLIC fillstr 



UT1LDLL 



EXPORT fillstr 




UT1LDEF 



LIBRARY 
EXPORTS fillstr 



IMPLIB 








UTILLIB 
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APP.C 



main 

{ 

jfillstr ( pszString ); 



APP.OBJ 



EXTRN fillstr 
call fillstr 



APP.EXE 



IMPORT util.fillstr 
call fillstr 



Preparing the .EXE 



UTILDEF 



LIBRARY 
EXPORTS fillstr 



IMPLiB 








UT1L.LIB 
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Variables in Main and in the DLL 



CHAR a; 
main (void) 

CHAR b; 

static CHAR c; 

dllsub ( a, b, o ); 



yy ///////// 



Appiicatio 
Data 



Application 
Code 



1 




Application 
Stack 




CHAR dlldata[28]; 

dllsub ( CHAR a, CHAR b, CHAR c) 

{ 

CHAR dlla; 

a = 'x'; 
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Methods of Dynamic Unking 



0 OS/2 supports two types of dynamic linking, 

v) Dynamic Linking at Load Time: 

Target code is loaded at loadtime. 
Procedure name is fixed in the .EXE file. 

@ Dynamic Linking at Run Time: 

Program creates the module name and 
the procedure name "on the fly". 

Target code is not loaded until it is needed. 
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Dynamic Linking at Run Time 

0 The process creates the module and procedure name. 

0 The process then calls DosLoadModule to find and load the 
target DLL module. 

0 A call to DosQueryProcAddr returns a pointer to the target procedure. 

0 The procedure is invoked directly through the pointer. 

0 When done, the process calls DosFreeModule to release 
the DLL module. 
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DosLoadModule 



DosLoadModule ( PSZ pszName, ~> ptr to msg. buffer 

ULONG cbName, <— size of msg. buffer 
PSZ pszModname, <~ name of module to load 
PHMODULE phmod ); — > ptr to returned module handle 



0 


NO ERROR 


127 


ERROR 


PROC NOT FOUND 


2 


ERROR 


FILE NOT FOUND 


Wl 


ERROR 


INVALID SEGMENT NUMBER 


3 


ERROR 


PATH NOT FOUND 


IN2 


ERROR 


INVALID ORDINAL 


4 


ERROR 


TOO MANY OPEN FILES 


190 


ERROR 


INVALID MODULETYPE 


5 


ERROR 


ACCESS DENIED 


191 


ERROR 


INVALID EXE SIGNATURE 


s 


ERROR 


NOT ENOUGH MEMORY 


192 


ERROR 


EXE MARKED INVALID 


11 


ERROR 


BAD FORMAT 


194 


ERROR 


ITERATED DATA EXCEEDS 64 K 


26 


ERROR 


NOT DOS DISK 


195 


ERROR 


INVALID MINALLOCSIZE 


32 


ERROR 


SHARING VIOLATION 


196 


ERROR 


DYNLINK FROM INVALID RING 


.y 


ERROR 


LOCK VIOLATION 


198 


ERROR 


INVALID SEGDPL 




ERROR 


SHARING.BUFFER .EXCEEDED 


199 


ERROR 


AUTODATASEG EXCEEDS 64 K 


as 


ERROR 


INTERRUPT 


3)1 


ERROR 


RELOCSCR CHAIN EXCEEDS SEGLIMIT 


KM 


ERROR 


DRIVE LOCKED 


3ft 


ERROR 


FILENAME EXCED RANGE 


in 


ERROR 


INVALID NAME 


395 


ERROR 


INIT ROUTINE FAILED 



DosLoadModule { SMsgbuf, 254, "MYDLL" , &hmod ); 
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DosQueryProcAddr, DosFreeModule 



DosQueryProcAddr (HMODULE hmod, <-- module handle 

ULONG ordinal, <-- ordinal number 
PSZ pszName, <— procedure name 
PFN *ppfn ); 



-> ptr to returned proe addr 



o NO_ERROR 

6 ERROR_INVALID_HANDLE 
123 ERROR_INVALID_NAME 
65079 ERROR_ENTRY_IS_CALLGATE 



I 



void ( *pfnReport) (PSZ pszMsg, APIRET rc, PSZ MyName ); 

rc = DosQueryProcAddr ( hmod, 0, "report", {PFN *) SpfnReport »; 
if (rc) exit (1); r ' 

pfnReport { "QueryProcAddress successful! \n" , 0, "INFOMSG: " ) ; 

DosFreeModule ( HMODULE hmod ); <-- module handle 



0 NO_ERROR 
6 ERROR_INVALID_HANDLE 
12 ERROR_INVALID_ACCESS 
95 ERROR INTERRUPT 
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Data Objects in DLLs 

0 Regular .EXE programs get unique copies of all data 
objects whenever the .EXE file is loaded (default). 

0 DLL modules do NOT. The loader will only load one 
copy of the data objects for DLL modules by default. 

0 This may be overridden with an entry in the module definition file 
DATA MULTIPLE NONSHARED 

0 DLL's use the stack memory of the calling process. 
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DLL Initialization 



DLL 



Application 



initialize ();> 
funct_a {); 
1unct_b 0; 




initialize () 
{ 

// perform initialization 

} 

funct_a 0 
{ 

// a DLL function 
} 

funct_b {) 
{ 

// a DLL function 

1 



® A DLL may need to perform initialization functions before the 
application invokes any procedures in the DLL. 

0 The initialization may involve: 
allocating memory 
creating or opening files 
setting up devices 
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Flow of Control for DLL Initialization 



OS/2 Loader 



© [C:\JAPP.EXE- 



2 APP.EXE 

funct_a (); 



■ Build app & DLL page 
tables and 'fixup* 
references 



call DLL initialization 
function 



■ Start application 
running 



DLL 



initialize () 

{ 

// perform initialization 
} 

funct_a {) 
{ 

// a DLL function 
} 

funct_b {) 
{ 

// a DLL function 
} 



0 The loader calls the DLL's initialization function before the 
application can call other DLL functions. This will also occur 
during DosLoadModule. 
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_DLL_lnitTerra 

unsigned long _DLL JnitTerm ( unsigned long modhandle, DLL file handle 

unsigned long flag); --> 0=init, l=term 

tpragma linkage { DLL_lnitTenn, system) 
int _CRT_init (void); 

unsigned long _DLL_InitTerm( unsigned long modhandle 

unsigned long flag ) 

switch ( flag ) /* 0 == load, 1 == freed */ 

case 0 : 

if { _CRT_init( ) == -1 ) return 0; 

printf ( "printf now works in _DLL_InitTerm{0) \n" ) 

break ; 
case 1: 
_CRT_term ( ) ; 

break; 

return 1; /* non-zero value returned to continue load */ 



IBM C Set/2 provides a default procedure, _DLL JnitTerm, which 
initializes and terminates the C run-time environment. 



0 The user may optionally provide a modified routine if additional 
initialization or termination actions are required by the user DLL. 
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Types of DLL Initialization 



DLL's Module Definition File 




default 



INITGLOBAL 



Loader calls the init. routine when the 1st process attaches 
to the DLL. This method is good if the DLL shares 
resources with all processes. 

INITINSTANCE Loader calls the init. routine each time a new process 

attaches to the DLL. This method allocates a new set of 
resources for each process. Implies TERMINSTANCE. 



0 INITINSTANCE may be combined with 'exit lists' to allocate and 
deallocate resources on a per process basis. 
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Exception Management 



Asynchronous/Synchronous Exceptions 
Signal Exceptions 
Registering Exception Handlers 
Exception Management Structures 
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System Exceptions 



0 An exception is an abnormal condition that can occur during 
program execution. 

0 Common causes of exceptions include: 
I/O errors 

Protection violations 
Math errors 

Intervention by the user or by another process 

0 Activities that can cause exceptions include: 
Invalid memory access 
Dividing by zero 
Pressing Ctrl+Break 
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Types of Exceptions 



0 Asynchronous Exceptions are caused by events that are external 
to the execution of the thread. 

0 An asynchronous exception may be caused by the user pressing 
Ctrl+Break or Ctrl+C, or by a process calling DosKillProcess. 

0 Synchronous exceptions are caused by events that are internal to 
the execution of the thread. 

0 Synchronous exceptions may be caused by: 
Invalid memory access 
Attempt to execute an illegal instruction 
Math calculation errors 
Illegal stack operation 
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Signal Exceptions 



0 Signal exceptions are asynchronous events sent to a thread when the 
user presses certain keys or when another thread or process initiates 
the exception. 

0 There are three types of signal exceptions: 
XCPT_S IGN AL_B RE A K - Ctrl+Break 
XCPT_SIGNAL_INTR - Ctrl+C 
XCPT_SIGNAL_KILLPROC - DosKillProcess 

0 All three signals are delivered by a single exception, XCPT_SIGNAL. 

0 The exception handler for thread 1 can handle none, some or all of 
the signals 

0 In order for a process to receive signal exceptions when multiple processes 
are running in the same screen group, the process must request signal 
exception focus (DosSetSignalExceptionFocus). 

0 A process can send the XCPT_SIGNAL exception to another process 
(DosSendSignalException). 
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Raising Exceptions 



0 Asynchronous exceptions that have been deferred in a must-complete 
section are dispatched automatically by the system when the section 
is exited. 

0 A synchronous exception that has been deferred must be raised by 
DosRaiseException. 

0 DosRaiseException can also be used to simulate either a synchronous 
or an asynchronous exception. 
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Error Pop-Up Screens 



0 Some error conditions, such as general protection violations, cause the 
operating system to display a pop-up screen containing information 
about the error. 



0 The application can disable error pop- up screens. 



0 DosError can disable or enable both exception and hard error pop-ups. 
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Exception Handlers 



0 The system provides a default exception handler which, in most cases, 
will terminate the application, 

0 The application can register its own subroutine to process exceptions, 
allowing it to avoid termination (DosSetExceptionHandler). 

0 If multiple exception handlers are registered, they are invoked in 
Last- In-First- Out order. 

0 If a process termination exception occurs and exit-list procedures have 
have been registered, the exit-list procedure will get control after the 
exception handler. 
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Exception Management Data Structures 



0 ExceptionRegistrationRecord 

Used to establish an exception handler. 

0 ExceptionReportRecord 
Describes an exception. 

0 ContextRecord 

Describes the machine state at the time of an exception. 

0 DispatcherContext 

Receives information on nested exceptions and collided unwinds. 
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ExceptionRegistrationRecord 



typedef struct .EXCEPTIONREGISTRATIONRECORD 

{ 

struct .EXCEPTIONREGISTRATIONRECORD * volatile prev_structure; // pfr to previous handler 

_err * volatile ExceptionHandler; // ptr to handler being registered 

} EXCEPTIONREGISTRATIONRECORD, 
* PEXCEPTIONREGISTRATIONRECORD 



@ When a procedure begins, it must create an ExceptionRegistrationRecord on 
the stack, fill in the pointer to the exception handler routine, and link to the 
front of the exception handler chain by calling DosSetExceptionHandler. 

0 When the procedure ends, it must remove the ExceptionRegistrationRecord 
from the chain by calling DosUnsetExceptionHandler. 
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ExceptionReportRecord 



_EXCEPTIONREPORTRECORD 



typedef struct 

ULONG ExccptionNum; 
ULONG fHandlerFlags; 
struct _EXCEPTIONREPORTRECORD 



// exception number 



// nesting/unwinding flags 
NestedExceptionReportRecord; 



// ptr to nested ExceptionReportRecord 
PVOID ExceptionAddress; // address where exception occurred 

ULONG c Parameters; // number of Exceptionlnfo elements 

ULONG ExceptionInfo[4]; // exception specific info 

EXCEPTIONREPORTRECORD, *PEXCEPTIONREPORTRECORD; 



0x0 XCPT UNKNOWN .ACCESS 

Oxl XCPT.RE AD. ACCESS 

aa XCPT.WRITE ACCESS 

0x4 XCPT_EXECUTE_ACCESS 

0x8 XCPT.SPACE. ACCESS 

Ox 10 XC PT.LIM (T_ ACCESS 



Oxl EH.NONCONTINUABL 
0x2 EH.UNWINDING 
0*4 EH .EXIT UNWIND 
0x8 EH.STACK.1N VALID 
OHIO EH NESTED.CALL 



OjcSttOJOOI XCPT.GUARD PAGE VIOLATION OxCOCXXXOT XCPT 

0x80010001 XCPT.U NAB LE.TO.GROW .STACK OxCO0COO98 XCPT 

OxC0000005 XCPT.ACCESS.VIOLATION 0xC0GC0099 XCPT 

C*CCOG(XX)_ XCPT. I N.PAGE ERROR OxCOOOCOSA XCPT 

DxCOOOOOlC XCPT.ILLEGAL. INSTRUCTION OxC000009B XCPT 

OxCOOOOOlD XCPT.INVALID.LOCK.SEQUENCE OxCOOOOOyC XCPT 

OxC00COC_4 XCPT.NONCONTINUABLE.EXCEPTION OxCOOOOOSD XCPT 

OxOXXXXKS XCPT INVALID.D1SPOS1TION OxCOOOOOSE XCPT 

OsQXXXXGIi XCPT UNWIND OxCOCXXXTSF XCPT 

(kaxx«XK7 XCPT BAD.STACK (hCOOOOOAO XCPT' 

0KCCOCO028 XCPT.INVALID.UNWIND TARGET OxCOOlOCOl XCPT 

0xOXXXX»3 XCPT .ARRAY BOUNDS EXCEEDED OxCOOlOOO. XCPT 

0x00000094 XCPT FLOAT.DENORMAL.OPERAND OxC00]O0O3 XCPT 

OxCOOOOffiS XCPT.FLOAT. DIVIDE BY ZERO 0x0X110004 XCPT 

fttC0O00O% XCPT.FLOATJNEXACT.RESULT 



.FLOAT. INV ALID.OPE RATION 

FLOAT.OVERFLOW 

FLO AT.ST A CK.CHECK 

.FLOAT.UNDERFI.OW 

INTEGER.DIVIDE_BY.ZERO 

INTEGER.OVERFLOW 

PRIVILEGED INSTRUCTION 

DATATYPE MISALIGNMENT 

BREAKPOINT 

SINGLE.STEF 

PROCESS.TERMINATE 

ASYNC PROCESS .TERMINATE 

SIGNAL 

BINPX.ERRATAJK 
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ContextRecord 



typedef struct .CONTEXT 



} 



ULONG ContextPIags; 
ULONG ctx_env[7]; 
FPREG ctx_stack[8]; 
ULONG ctx_SegGs; 
ULONG ctx_SegFs; 
ULONG ctx_ScgEs; 
ULONG ctx_SegDs; 
ULONG ctx^RegEdi; 
ULONG ctxJlegEsi; 
ULONG ctx_RegEax; 
ULONG ctx_RegEbx; 
ULONG ctx_RegEcx; 
ULONG ctx_RegEdx; 
ULONG ctx_RegEbp; 
ULONG ctx_RegEip; 
ULONG ctx_SegCs; 
ULONG ctx_EFlags; 
ULONG ctx_RegEsp; 
ULONG ctx.SegSs; 
CONTEXTRECORD, *PCONTEXTRECORD; 



> 



CONTEXT_FLOATING_POINT OxOOOOOOOSL 



CONTEXT_SEGMENTS 



CONTEXT JNTEGER 



Ox00000004L 



Ox00000002L 



CONTEXT_CONTROL 



OxOOOOOOOlL 
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Exception Handling Example 



// pagefalt.c example of page fault exception handler 

{define incl DOS 
define INCLTi OS ERRORS 
(define INCL~~DOSEXCEPTIONS 
(include <os~Z.h> 
(include <stdio.h> 

(define STDOUT 1 
(define STDERR 2 

API RET APIENTRY MyHandler [ PEXCEPTIONREFORTRECORD pERepRec, 

PEXCEPTIQNREGISTRATIONREC0R& pEflegRec, 
PCONTEXTRECORD pCtxRec , 

PVOID p )} // ptr to dispatcher context 

void terminate I PSZ pszMsg, APIRET rc, PSZ pszMyName ) ; 
void querymem [PCH pchstartQuery, ULONG ulLengthl ( 

void main ( void) 

E XCE P T I ON RE G I STRATI ON RECORD X cpt h a nd ; 
AP IRET rc ' 

PSZ pazMyName = " PAGE F ALT: " : 
PCH pBuf; 
ULONG ulAttr; 
ULONG ulX; 

setbuf ( stdout, NULL } ; 

xcpthand.prev structure = END OF CHAIN ; 
xcpthand.ExceptionHandler - MyHaTTdler; 

rc = DOSError ( FERR DISABLEEXCEPTION I FERR DISABLEHARDERR ) ; // disable pop-ups 
if [rc) terminate { "DosError problem\n* , rc, pszMyName) ; 

rc =DosSetExceptionHandler ( txcpthand ); 

if {rc) terminate < "SetExceptionHandler problem\n" , rc, pszMyName) ; 

rc - DosAllocMem ( (PVOID) SpBuf, B192, PAG READ I PAG WRITE ); 
if (rc) terminate {"'AllocMem error\n", rc, pszMyName)? - 

rc = DOsEetMem ( pBuf, 4096, PAG COMMIT I PAG DEFAULT ) ; 

if (rc) terminate ("SetMem errorTn", rc, pszMyName) ; 
for (UlX = 4090; ulX <: 4100; ulX++) 
pBufrulxi - 'l'j 

^rintf ("ulX = id pBuf[ulX] - %x\n", ulx, pBuf[ulX] )j 
rc - DosUnsetExceptionHandler ( &xcpthand ) ; 

if (rc) terminate ( "UnsetExceptionHandler problem\n", rc, pszMyName); 
printf [ "TerminatingVn" ) ; 
DosExit ( EXITPROCESS, NO_ERROR ); 
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Exception Handling Example cont'd 

APIRET API ENTRY MyHandler ( PE XCEPT I ONREPORTRE CORD pERepRec, 

PE XCE F TI ONREG 1 5TRAT I ONRE CORD pE Re gRec , 
FCONTEXTRECORD pCtxRec, 
PVOID p > 

{ 

ULONG cbWritten, ulMemSize, flMemAttrs; 
APIRET re; 

/ / Access violation at a know location 

if { pERepRec-:>ExceptionNum — XCPT ACCESS VIOLATION St 

pERepRec->ExceptionAddresB 1= TP VOID )~XCPT_DATA_[JNKNOWN } 

// page fault 

if ( ( pERepRec->ExceptianInfo[01 — XCPT READ ACCESS II 

pERepRec->ExceptiOnInfo[ U j == XCPT - WRITE ACCESS) 56 
pERepRec - 5-E xc ept ion I n f o [ 1 ] != XC P"rT>ATA_UNKNOWN ) 

DosWrite ( STDERR, "\r\nHANDLER: Page Fault\r\n", 24, ScbWritten ) 

/ 1 now query the memory to find out why we faulted 

UlMemSize ■ 1; 

DosQueryKem { (PVOID) pF.RepRec->ExceptionInfo( 1 ] , 
sulMemSize, iflMemAttrs \; 

II If the memory is free or committed, we have some other problem. 
// If it is not free or not committed, commit it . 

if ( M f lHemAttrs £ ( PAC_FREE | PAG_COMMIT ) ) } 

DoaWrite ( STDERR, " \r\nHANDLER : Attempt to access "\ 
"uncommitted memory\r\n", 49, fccbWritten ); 

re - DosSetHem ( (PVOID) pERepRec->ExceptionInfo[ 1 ] , 1, 
PAG_DEFAuLT \ PAG_COMMIT ) ; 

if ( rc ) 
{ 

DosWrrte ( STDERR, "\r\nError committing memory \r\n" , 

27, icbWritten ) ; 
return { XCPT_CONTINUE_SEARCH ); // not handled 

else 

return ( XCPT continue EXECUTION ) ; // handled 
) // end if 
} // end if 
> // end if 

return ( XCPT_CONTINUE SEARCH ) ; // not handled 
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Summary of Exception Related Functions 



DosAcknowledgeSignalException 

DosEnterMustComplete 

DosExitMustComplete 

DosRaiseException 

DosSendSignalException 

DosSetExceptionHandler 

DosSetSignalExceptionFocus 

DosUnsetExceptionHandler 

DosUnwindException 
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Session Management 



Session Resources 
Session Management 
Session Hierarchy 
Session Startup 
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Overview of Sessions, Processes, & Threads 



0 Session - A collection of one or more processes associated 
with a virtual console 

@ Process - A collection of one or more threads and associated 
system resources. 

0 Thread - A dispatchable unit of work 



0 Resources are distributed between Sessions, Processes, and Threads, 
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Session Resources 



0 Video Buffer 

0 Keyboard Buffer 

0 Mouse Buffer 

0 Session ID 

0 Child Session 
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Session 




0 A session is one or more processes that all share the 
same keyboard, mouse, and display. 

0 A maximum of 255 sessions is permitted. Those sessions 
may be any mixture of Full Screen, Graphic Window, Text 
Window or Virtual Dos Machines. 

0 Each session contains at least one process. 
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Session Management Components 



I 
1 

X 



User 
Shell 




Foreground 



Application 
#1 



Session Manager API 



Session Manager 




Background 



Kernel 



Hardware 



Application 
#n 



Session(s) 





LVB 








KBQ 








MEQ 





Subsystems 



Background 



0 The Session Manager switches the 'focus' of the subsystem to 
the correct application. 
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Session Hierarchy 




0 A session can create other related or independent sessions. 

0 Sessions are created by: 

Programs through the DosStartSession API 
Users through the START command 

0 Each session has a session ID # (SESSID). 

0 If a child session is stopped, all descendants are stopped. 
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Creating A Session 



0 DosStartSession creates independent or dependent (child) sessions. 

0 A Newly created session can be started in the foreground or background. 

0 A Session ID and a process ID are returned to the Parent Session 
(valid only if Child Session). 

0 The process in the new session can be the command processor . 

0 A termination queue may be set up so that parent sessions can be 
notified when child sessions terminate. 
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DosStartSession 

DosStartSession (PSTARTDATA psd, 
PULONG pidSession, 
PPID ppid); 



NO_ERROR 

ERROR_SMG_INVALID_SESSION_ID 
ERROR_SMG_INVALID_CALL 
ERROR_SMG_PROCESS_NOT_PARENT 
ERROR_SMG_RETRY_SUB ALLOC 



START DATA startdata; 
startdata. Length - 24; 

startdata. Related - SSF RELATED CHILD; 
startdata, FgBg = SSF_FGEG BACK; - 
startdata.TraceOpt = SSF TRACE OPT NONE; 
startdata. FgmTitle = "Browse"; _ 
startdata, PgmName = "c:\os201abs\browse.exe' 
startdata. Pgmlnputs = "browse\0 main . c\0\ 0 " ; 
startdata. TermQ - 0; 

DosStartSession ( &startdata, SpidSession, 

&pid ) ; 



<— start session data 
— > returned session id 
— > returned process id 



typedef struct .STARTDATA { 

USHORT Length; 

USHORT Related; 

USHORT FgBg; 

USHORT TraceOpt; 

PSZ PgmTitle; 

PSZ PgmName; 

PBYTE Pgmlnputs; 

PBYTE TermQ; 

PBYTE Environment; 

USHORT InheritOpt; 

USHORT SessionType; 

PSZ IconFile; 

ULONG PgmHandle; 

USHORT PgmControl; 

USHORT InitXPos; 

USHORT InitYPos; 

USHORT InitXSize; 

USHORT InitYSize; 

USHORT Reserved; 

PSZ ObjectBuffer; 

ULONG ObjectBuffLen; 
} STARTDATA, *PSTARTDATA; 
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Setting Selectability and Bonding of a Child Session 



0 When a child session is selectable, the user can select it from the 
Window List or by using Alt+Esc. 

0 When a child session is nonselectable, the user CANNOT select 
the session. 

0 An application can establish a bond between a parent session and 
one of its child sessions. 

0 When the two sessions are bound, the operating system brings the child 
session to the foreground when the user selects the parent session. 
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DosSetSession 



DosSetSession ( ULONG idSession, 

PSTATUSDATA psd 



<— session id 
); <— ptr to status data structure 



0 NO_ERROR 
369 ERROR_SMSG_INVALID_SESSION_ID 
418 ERROR_SMSG_INVALID_CALL 

455 ERROR_SMSG_INVALID_BOND_OPTION 

456 ERROR_SMSGJNVALID_SELECT_OPT 

460 ERROR_SMSG_PROCESS_NOT_PARENT 

46 1 ERROR_SMSG_IN V ALID_DAT A_LENGTH 
463 ERROR_S MSG_RETR Y_SUB_ALLOC 



typcdef struct _STATUSDATA { 

USHORT Length; /* 6 */ 

USHORT Selectlnd; 

USHORT Bondlnd; 

} STATUSDATA, *PSTATUSDATA; 



0 SET_SESSION_UNCHANGED 

1 SET_SESSION_SELECTABLE 

2 S ET_S ES S I ON_N ON_S ELECT ABLE 

1 SET_SESSION_BOND 

2 SET_SESSION_NO_BOND 

0 This function may only be called by a parent session and only for 
a child session. 

0 The status of a session that was started as unrelated cannot be changed. 

0 When a bond is established with a child session, any bond that the parent 
had with another child session is broken. 

STATUSDATA statusdata; 
statusdata . length = 6 

statusdata. Selected = SET SESSION UNCHANGED; 
statusdata. Bondlnd = SET_5ESSIQN B"OND; 
DosSetSession ( idSession, fcstatusdata ) ; 
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DosSelectSession 



DosSelectSession ( ULONG idSession ); 



0 NO_ERROR 
224 ERROR_SMGJMO_TARGET_ WINDOW 
369 ERRQR_SMG_INVALID_SESSION_ID 
418 ERROR_SMGJNVALID_CALL 

459 ERROR_SMG_BAD_RESERVE 

460 ERROR_SMG„PROCESS_NOT_PARENT 
463 ERROR_SMG_RETRY_SUB_ALLOC 



0 A parent can force itself or any child session to the foreground. 

0 DosSelectSession only works if parent or any child is already 
in the foreground. 

0 If a child terminates while in the foreground, the parent becomes 
the foreground session. 

® The PARENT HAS CONTROL! 
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DosStopSession 



DosStopSession (ULONG scope, ULONG idSession ); 



0 NO_ERROR 
224 ERROR_SMG_NO_TARGET_ WINDOW 
418 E RROR_S M G„I N V AL I D_C A LL 

458 ERROR_SMG_INVALID_STOP_OPTION 

459 ERROR_SMG_BAD_RESERVE 

460 ERROR_SMG_PROCESS_NOT_PARENT 
463 ERR OR_SMG_RETRY_SUB_ ALLOC 



'0 STOP_SESSION_SPECIFIED 
1 STOP_SESSION ALL 



0 Can only be used by a parent session to stop one or all of its 
child sessions. 

0 If the specified child session has related sessions, the related sessions 
are also terminated. 

0 The parent session may be running in the foreground or background. 

0 If the child session is running in the foreground when it is terminated, 
the parent session becomes the foreground session. 

DosStopSession ( STOP SESSION ALL, idSession ) ; 
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Pipes 



Anonymous Pipes 
Standard Input/Output 
Duplicating File Handles 
Named Pipes 
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Standard Input/Output 



'C Example of Using Standard Input/Output 

/* lower. c — converts uppercase characters to lower case */ 

♦include <stdio.h> 
♦include <ctype . h> 

main ( int argc, char * argv[], char * envp[ ] ) 
{ char ch; 

while ( ( ch = getchar( ) ) 1= EOF ) // read STDIN 
putchar ( tolower ( ch ) )- // write STDOUT 

} 



0 Standard devices can be redirected to other devices, files 
or pipes. 

0 A child process could inherit Standard device handles that 
have been redirected to pipe handles. 
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Anonymous Pipes 



0 A data storage buffer that OS/2 maintains. 

0 The maximum size of the buffer is 64 Kb. 

0 Similar to a file in that it is read and written via the file handle 
operations DosRead and DosWrite. 

0 Differs from a file in that the data may only be accessed in 
FIFO fashion. 

0 Since a child process inherits file handles from the parent, 
anonymous pipes are used to communicate between 
related processes. 
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Using Anonymous Pipes 




0 Two pipes must be created to provide bidirectional communication. 

0 Standard device handles are redirected to the pipe read/write 
handles with DosDupHandle. 
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DosCreatePipe, DosDupHandle 



/ DosCreatePipe ( PHFILE phfRead, -> ptr to returned read handle 
/ PHFILE phfWrite, --> ptr to returned write handle 

/ ULONGcb ); <-- size of pipe buffer 

'o NO_ERROR ~ 

8 ERROR_NOT_ENOUGH_MEMORY 



DosCreatePipe { ShfRead, &hfWrite, 1024 ); 



DosDupHandle ( HFILE hFile, <-- handle to be duplicated 
PHFILE phFile ); <— > ptr to duplicate 



o NO_ERROR 
4 ERROR_TOO„MANY_OPEN_FILES 
6 ERROR_INVALID_HA NDLE 
114 ERROR_INVALID_TARGET HANDLE 



HFILE hNewHandle = STDIN; 
DosDupHandle ( hfRead, ShNewHandle ); 
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Pipes/Redirection Example 
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Named Pipes 



0 Like anonymous pipes, they provide serial communication 
between two processes. 

0 Users of the named pipe need not be related. 

0 Named pipes can be used in byte- stream or message mode. 

0 Named pipes may be full duplex. A single handle is used for both 
reading and writing. 

0 Named pipes work both locally on a single system and remotely 
across a network. 

0 DOS workstations may communicate with an OS/2 server 
through named pipes. 
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Server/Client Communication Using Named Pipes 



0 The server process creates the pipe by calling DosCreateNPipe. The 
pipe is now 'disconnected' and cannot be opened by a client process. 

0 The server process calls DosConnectNPipe to put the pipe into the 
'listening' mode. 

0 A client process supplies the name of the pipe in a call to DosOpen 
and receives a pipe handle. The pipe is now in the 'connected' state. 

0 The server and client process communicate by calling DosRead, 
DosWrite or DosTransactNPipe. 

0 The client process calls DosClose to close its end of the pipe. The pipe 
is now in the 'closing' state and cannot be accessed by another client. 

0 The server process calls DosDisconnectNPipe. The pipe is now in the 
'disconnected' state again. 

0 To enable another client, the server must call DosConnectNPipe again. 
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Named Pipe Server Program Example 

// example multi-thread server program for Named Pipes pipeserv.c 

(frdefine INCL_BASE 
iinclude <os2.h> 
Iinclude <stdio.h> 
# include <stdlib.h> 
#include <string.h> 
Iinclude <malloc.h> 

Idefine PIPE_NAME " \ \pipe Wexample" 

fdefine LOWER_CASE OFFSET ('a' - 'A') 
#define STDOUT 1 

HEV server_sem = 0; 

OSHORT connection_id = 0; 

HPIPE pipe_handle; 

BOOL flContinue = TRUE; 

/ / internal functions 
void thread (void); 

// external functions 

void terminate { PSZ pszMsg, API RET rc, PSZ pszMyName) ; 

int main ( void ) 
{ 

TID thread_id; 

PSZ pszMyName = "PIPESERV:"; 

APIRET rc ; 

while ( flContinue ) 
{ 

/ / create an instance of the named pipe 

rc = DosCreateNPipe ( PIPE_NAME, Epipe_handle , NP_ACCESS_DUPLEX, 

NP_WAIT I NP_READMODE_MESSAGE | 
NP_TYPE_MESSAGE | NP UNLIMITED INSTANCES, 
128, 128, 0 ); 

if (rc) terminate ("Error Creating PipeW , rc, pszMyName); 
DosEnterCritSec ( ) ; 

printf ("%s Pipe Instance Created. Waiting for a "\ 

"connection. . . \n" , pszMyName ) ; 
DosExitCritSec ( ) ; 

// put pipe in 'listening' mode and wait for a connection 
rc = DosConnectNPipe ( pipe_handle ) ; 

if(rc) terminate ("Error Connecting Pipe\n", rc , pszMyName); 
printf ("%s Connection ReceivedNn", pszMyName); 

// create event sema4. Server thread will post when it starts 
rc = DosCreateEventSem ( 0, &server__sem, 0, FALSE ); 
if (rc) terminate ("Error Creating EventSemVn" , rc, pszMyName); 

/ / create a server thread 

rc = DosCreateThread ( &thread_id, (PFNTHREAD) thread, 0, 0, 8192 ); 
if (rc) terminate ("Error Creating Server ThreadVn" , rc, pszMyName); 
printf ("%s Server Thread Created\n" , pszMyName); 

// wait for signal that thread is running 

rc = DosWaitEventSem ( server_sem, 1000 ) ; 

if (rc) terminate ("Error waiting for thread sema4\n" , rc, pszMyName); 
} // end while 

return 0; 

> 
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Named Pipe Server Program Example cont' 

// thread to manage a server connection pipeserv.c 

void thread { void ) 

{ 

APIRET rc; 

USHORT my connection; 

HPIPE hPipe; 

BOOL keep connection - true ; 

CHAR buffer[ 128]; 

ULONG bytes read; 

USHORT index~= 0; 

ULONG bytes written; 

PSZ pszMyName = "SERVTHRD : " ; 

/ / bump the connection count 
connection_id += 1; 

II get my connection id 

my_connection = connection_id; 

/ / get my pipe handle 

hPipe ~ pipe handle; 

— 

/ / signal the main thread so it can continue 

printf ("%s Connection #%d\n", pszMyName, my_connection ) ; 
DosPostEventSem ( server_sem ) ; 

while ( keep_connection ) 

// read a message from the pipe 

rc = DosRead ( hPipe, buffer, 128, sbytes read ); 
if trc) 

keep connection = FALSE; 
brealt ; 

// print message 

DosEnterCritSec ( ) ; 

printf ("%s%d Message received: %s\n", 

pszMyName, my connection, buffer ) ; 
DosExitCritSec { ) ; 

// process and write it back 

while ( index < strlen (buffer) ) 

* if ( ( buffer [index] >= 'a' ) && ( buf fer [ index ] <= 'Z')) 
buffer[ index] -= LOWER_CASE_OFFSET ; 
index += 1 ; 
} II end while 

rc = DosWrite (hPipe, buffer, strlen (buffer), Sbytes written ); 
if (rc) terminate ("Error Writing Pipe\n" , rc, pszMyName); 

// if 'done', drop thru and disconnect 

keep_connection - (stricmp (buffer, "done") != 0 ); 
} // end while 

// disconnect and close the pipe 

rc = DosDisConnectNPipe ( hPipe ) ; 

if (rc) terminate ("Error Disconnecting Pipe\n", rc, pszMyName); 
printf ("%s%d DisconnectingXn" , pszMyName, my_connection) ; 

// close the pipe 

rc = DosClose ( hPipe ) ; 

if (rc) terminate ("Error Closing Pipe\n", rc, pszMyName); 

/ / exit the thread 

DosExit ( EXIT THREAD, 0); 

} 

20PIPE10 921129 



19-10 



Named Pipe Client Program Example 

// example client program for Named Pipes 

// pipeclnt.c 

#define INCL BASE 

#include <os7.h> 

#include <stdio.h> 

tinclude <stdlib.h> 

tinclude <string.h> 

#define STDOUT 1 

// external functions 

void terminate { PSZ pszMsg, APIRET rc, PS2 pszMyName); 

int main { void ) 
{ 

APIRET rc = 0; 

HPIPE pipe; 

ULONG action; 

CHAR pipe name [611; 

CHAR inputT[64]; 

PSZ pszMyName = "PIPECLNT : " : 

CHAR result[64]; 

ULONG bytes_returned ; 

// get name server. If no server name entered, connect locally 

printf ("Enter the server name or <Enter>: \n"): 
gets ( input ) ; 

if ( input [0] != '\0' ) 

strcpy (pipe_name, "WW"); 
strcat <pipe_name, input); 
strcat (pipe_name, "\ \pipeW example" ) ; 

else 

strcpy (pipe_name, " WpipeW example " ) ; 

/ / wait for available instance of pipe 

rc = DosWaitNPipe ( pipe name, SEM INDEFINITE WAIT ); 
if (rc) terminate ("Error waiting Tor pipe in"s"tance\n" , 

rc, pszMyName); 
printf ("%s Pipe AvailableW' , pszMyName); 

rc - DosOpen ( pipe name, &pipe, S action, 0, 0, 
OPEN-ACTION OPEN IF EXISTS, 

0 PEN - ACC E S S - R E ADWR I TE T OPEN SHARE DENYREAD WRITE I 
OPENTLAGS WRITE THROUGH, 0 T; _ 1 
if (rc) terminate {"*Error opening pipe\n", rc, pszMyName); 

printf ("%s Pipe Opened\n", pszMyName); 

rc = DosSetNPHState ( pipe, NP READMODE MESSAGE ); // chg. mode 
if (rc) terminate ("Error changing Pipe~Mode\n" , rc, pszMyName); 

printf ("%s Pipe Mode ChangedW, pszMyName); 

while ( stricmp ( input, "done" ) != 0 ) 

printf ("Enter string to transmit : \n" ) ,- 
gets { input ) ; ' 

rc = DosTransactNPipe ( pipe, input, strlen (input) +1, result, 

64 , &bytes returned ) ; 
if (rc) terminate ("Error in TransSctNPipeW , rc, pszMyName); 

result [ by tes_returned] - '\0'; 

printf ("Result: %s\n", result ); 

rc = DosClose ( pipe ) ; 

if (rc) terminate ("Error Closing PipeXn", rc, pszMyName); 
return u" %S Closin S the pi P e ^ n " i pszMyName); 

20PIPE11 921208 



19-11 



Summary of Named Pipe Functions 



DosCallNPipe DosQueryNPipelnfo 

DosConnectNPipe Dos Query NPipeSemState 

DosCreateNPipe DosSetNPHState 

DosDisConnectNPipe DosSetNPipeSem 

DosPeekNPipe DosTransactNPipe 

DosQueryNPHState DosWaitNPipe 
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